annotate lispref/edebug.texi @ 79359:53328e172cbc

(ido-save-history): Write the history file in UTF-8, and add `coding' file-local variable.
author Juanma Barranquero <lekktu@gmail.com>
date Sat, 10 Nov 2007 00:27:50 +0000
parents 1f4b88ab053d
children a1e16e813aed 4ef881a120fe
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @comment -*-texinfo-*-
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
75250
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 73400
diff changeset
3 @c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004,
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 73400
diff changeset
4 @c 2005, 2006, 2007 Free Software Foundation, Inc.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
5 @c See the file elisp.texi for copying conditions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
7 @c This file can also be used by an independent Edebug User
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
8 @c Manual in which case the Edebug node below should be used
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @c with the following links to the Bugs section and to the top level:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 @c , Bugs and Todo List, Top, Top
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
13 @node Edebug, Syntax Errors, Debugger, Debugging
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 @section Edebug
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
15 @cindex Edebug debugging facility
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 Edebug is a source-level debugger for Emacs Lisp programs with which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 you can:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 Step through evaluation, stopping before and after each expression.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 Set conditional or unconditional breakpoints.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 Stop when a specified condition is true (the global break event).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 Trace slow or fast, stopping briefly at each stop point, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 at each breakpoint.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 Display expression results and evaluate expressions as if outside of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
38 @item
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
39 Automatically re-evaluate a list of expressions and
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 display their results each time Edebug updates the display.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 Output trace info on function enter and exit.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 Stop when an error occurs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 Display a backtrace, omitting Edebug's own frames.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 Specify argument evaluation for macros and defining forms.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 Obtain rudimentary coverage testing and frequency counts.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 The first three sections below should tell you enough about Edebug to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 enable you to use it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 * Using Edebug:: Introduction to use of Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 * Instrumenting:: You must instrument your code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 in order to debug it with Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 * Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 * Jumping:: Commands to jump to a specified place.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 * Misc: Edebug Misc. Miscellaneous commands.
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
68 * Breaks:: Setting breakpoints to make the program stop.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
69 * Trapping Errors:: Trapping errors with Edebug.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 * Views: Edebug Views. Views inside and outside of Edebug.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
71 * Eval: Edebug Eval. Evaluating expressions within Edebug.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 * Eval List:: Expressions whose values are displayed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 each time you enter Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 * Printing in Edebug:: Customization of printing.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 * Trace Buffer:: How to produce trace output in a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 * Coverage Testing:: How to test evaluation coverage.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 * The Outside Context:: Data that Edebug saves and restores.
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
78 * Edebug and Macros:: Specifying how to handle macro calls.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 * Options: Edebug Options. Option variables for customizing Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 @node Using Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 @subsection Using Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 To debug a Lisp program with Edebug, you must first @dfn{instrument}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 the Lisp code that you want to debug. A simple way to do this is to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 first move point into the definition of a function or macro and then do
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 @kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 @ref{Instrumenting}, for alternative ways to instrument code.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 Once a function is instrumented, any call to the function activates
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
92 Edebug. Depending on which Edebug execution mode you have selected,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
93 activating Edebug may stop execution and let you step through the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
94 function, or it may update the display and continue execution while
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
95 checking for debugging commands. The default execution mode is step,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
96 which stops execution. @xref{Edebug Execution Modes}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 Within Edebug, you normally view an Emacs buffer showing the source of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 the Lisp code you are debugging. This is referred to as the @dfn{source
26254
a393c5e46e99 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
100 code buffer}, and it is temporarily read-only.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101
60498
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
102 An arrow in the left fringe indicates the line where the function is
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 executing. Point initially shows where within the line the function is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 executing, but this ceases to be true if you move point yourself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 If you instrument the definition of @code{fac} (shown below) and then
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
107 execute @code{(fac 3)}, here is what you would normally see. Point is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
108 at the open-parenthesis before @code{if}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 (defun fac (n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 =>@point{}(if (< 0 n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 (* n (fac (1- n)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 @cindex stop points
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 The places within a function where Edebug can stop execution are called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 @dfn{stop points}. These occur both before and after each subexpression
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
120 that is a list, and also after each variable reference.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
121 Here we use periods to show the stop points in the function
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @code{fac}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 (defun fac (n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 .(if .(< 0 n.).
54024
9f3c718e5096 (Using Edebug): Fix example.
Richard M. Stallman <rms@gnu.org>
parents: 53595
diff changeset
127 .(* n. .(fac .(1- n.).).).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 1).)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 The special commands of Edebug are available in the source code buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 in addition to the commands of Emacs Lisp mode. For example, you can
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 type the Edebug command @key{SPC} to execute until the next stop point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 If you type @key{SPC} once after entry to @code{fac}, here is the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 display you will see:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 (defun fac (n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 =>(if @point{}(< 0 n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 (* n (fac (1- n)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 When Edebug stops execution after an expression, it displays the
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
145 expression's value in the echo area.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 Other frequently used commands are @kbd{b} to set a breakpoint at a stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 exit Edebug and return to the top-level command loop. Type @kbd{?} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 display a list of all Edebug commands.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 @node Instrumenting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 @subsection Instrumenting for Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 In order to use Edebug to debug Lisp code, you must first
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @dfn{instrument} the code. Instrumenting code inserts additional code
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
157 into it, to invoke Edebug at the proper places.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @kindex C-M-x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @findex eval-defun (Edebug)
60498
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
161 When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
162 prefix argument on a function definition, it instruments the
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
163 definition before evaluating it. (This does not modify the source
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
164 code itself.) If the variable @code{edebug-all-defs} is
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
165 non-@code{nil}, that inverts the meaning of the prefix argument: in
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
166 this case, @kbd{C-M-x} instruments the definition @emph{unless} it has
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
167 a prefix argument. The default value of @code{edebug-all-defs} is
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
168 @code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
169 of the variable @code{edebug-all-defs}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
171 @findex eval-region @r{(Edebug)}
71629
38ef9c5576bb (Instrumenting): Add Edebug-specific findex for eval-buffer.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 68648
diff changeset
172 @findex eval-buffer @r{(Edebug)}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
173 @findex eval-current-buffer @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 If @code{edebug-all-defs} is non-@code{nil}, then the commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 also instrument any definitions they evaluate. Similarly,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 @code{edebug-all-forms} controls whether @code{eval-region} should
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 instrument @emph{any} form, even non-defining forms. This doesn't apply
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 to loading or evaluations in the minibuffer. The command @kbd{M-x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 edebug-all-forms} toggles this option.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @findex edebug-eval-top-level-form
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
183 Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
184 instrument any top-level form regardless of the values of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
185 @code{edebug-all-defs} and @code{edebug-all-forms}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
187 While Edebug is active, the command @kbd{I}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 (@code{edebug-instrument-callee}) instruments the definition of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 function or macro called by the list form after point, if is not already
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 instrumented. This is possible only if Edebug knows where to find the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
191 source for that function; for this reading, after loading Edebug,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
192 @code{eval-region} records the position of every definition it
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
193 evaluates, even if not instrumenting it. See also the @kbd{i} command
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
194 (@pxref{Jumping}), which steps into the call after instrumenting the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
195 function.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
197 Edebug knows how to instrument all the standard special forms,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
198 @code{interactive} forms with an expression argument, anonymous lambda
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
199 expressions, and other defining forms. However, Edebug cannot determine
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
200 on its own what a user-defined macro will do with the arguments of a
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
201 macro call, so you must provide that information using Edebug
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
202 specifications; see @ref{Edebug and Macros}, for details.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
204 When Edebug is about to instrument code for the first time in a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
205 session, it runs the hook @code{edebug-setup-hook}, then sets it to
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
206 @code{nil}. You can use this to load Edebug specifications
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
207 associated with a package you are using, but only when you use Edebug.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
208
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
209 @findex eval-expression @r{(Edebug)}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
210 To remove instrumentation from a definition, simply re-evaluate its
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 definition in a way that does not instrument. There are two ways of
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
212 evaluating forms that never instrument them: from a file with
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 @code{load}, and from the minibuffer with @code{eval-expression}
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
214 (@kbd{M-:}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 If Edebug detects a syntax error while instrumenting, it leaves point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 at the erroneous code and signals an @code{invalid-read-syntax} error.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @xref{Edebug Eval}, for other evaluation functions available
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 inside of Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 @node Edebug Execution Modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @subsection Edebug Execution Modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @cindex Edebug execution modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 Edebug supports several execution modes for running the program you are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 debugging. We call these alternatives @dfn{Edebug execution modes}; do
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
228 not confuse them with major or minor modes. The current Edebug execution mode
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 determines how far Edebug continues execution before stopping---whether
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 it stops at each stop point, or continues to the next breakpoint, for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 example---and how much Edebug displays the progress of the evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 before it stops.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 Normally, you specify the Edebug execution mode by typing a command to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 continue the program in a certain mode. Here is a table of these
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
236 commands; all except for @kbd{S} resume execution of the program, at
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 least for a certain distance.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 @item S
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
241 Stop: don't execute any more of the program, but wait for more
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 Edebug commands (@code{edebug-stop}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @item @key{SPC}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @item n
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 Next: stop at the next stop point encountered after an expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
250 @ref{Jumping}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @item t
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
253 Trace: pause (normally one second) at each Edebug stop point
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
254 (@code{edebug-trace-mode}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 @item T
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 Rapid trace: update the display at each stop point, but don't actually
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 pause (@code{edebug-Trace-fast-mode}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @item g
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 @item c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 Continue: pause one second at each breakpoint, and then continue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 (@code{edebug-continue-mode}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 @item C
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 Rapid continue: move point to each breakpoint, but don't pause
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 (@code{edebug-Continue-fast-mode}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 @item G
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 can still stop the program by typing @kbd{S}, or any editing command.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 In general, the execution modes earlier in the above list run the
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
277 program more slowly or stop sooner than the modes later in the list.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 While executing or tracing, you can interrupt the execution by typing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 any Edebug command. Edebug stops the program at the next stop point and
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
281 then executes the command you typed. For example, typing @kbd{t} during
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
282 execution switches to trace mode at the next stop point. You can use
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
283 @kbd{S} to stop execution without doing anything else.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 If your function happens to read input, a character you type intending
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 to interrupt execution may be read by the function instead. You can
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 avoid such unintended results by paying attention to when your program
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 wants input.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @cindex keyboard macros (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 Keyboard macros containing the commands in this section do not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 completely work: exiting from Edebug, to resume the program, loses track
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 of the keyboard macro. This is not easy to fix. Also, defining or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 executing a keyboard macro outside of Edebug does not affect commands
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
295 inside Edebug. This is usually an advantage. See also the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297
60498
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
298 When you enter a new Edebug level, the initial execution mode comes
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
299 from the value of the variable @code{edebug-initial-mode}.
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
300 (@xref{Edebug Options}.) By default, this specifies step mode. Note
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
301 that you may reenter the same Edebug level several times if, for
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
302 example, an instrumented function is called several times from one
f779a0469755 (Using Edebug): Arrow is in fringe.
Richard M. Stallman <rms@gnu.org>
parents: 60376
diff changeset
303 command.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
305 @defopt edebug-sit-for-seconds
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
306 This option specifies how many seconds to wait between execution steps
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
307 in trace mode. The default is 1 second.
52849
3e34838fbfac Fix typo.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52840
diff changeset
308 @end defopt
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @node Jumping
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @subsection Jumping
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 The commands described in this section execute until they reach a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 specified location. All except @kbd{i} make a temporary breakpoint to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 establish the place to stop, then switch to go mode. Any other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 breakpoint reached before the intended stop point will also stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 execution. @xref{Breakpoints}, for the details on breakpoints.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 These commands may fail to work as expected in case of nonlocal exit,
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
320 as that can bypass the temporary breakpoint where you expected the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
321 program to stop.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 @item h
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 Proceed to the stop point near where point is (@code{edebug-goto-here}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @item f
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
328 Run the program for one expression
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 (@code{edebug-forward-sexp}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 @item o
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 Run the program until the end of the containing sexp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 @item i
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 Step into the function or macro called by the form after point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
338 The @kbd{h} command proceeds to the stop point at or after the current
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
339 location of point, using a temporary breakpoint.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 The @kbd{f} command runs the program forward over one expression. More
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 precisely, it sets a temporary breakpoint at the position that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @kbd{C-M-f} would reach, then executes in go mode so that the program
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 will stop at breakpoints.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 With a prefix argument @var{n}, the temporary breakpoint is placed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 @var{n} sexps beyond point. If the containing list ends before @var{n}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 more elements, then the place to stop is after the containing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 expression.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
351 You must check that the position @kbd{C-M-f} finds is a place that the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
352 program will really get to. In @code{cond}, for example, this may not
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
353 be true.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
355 For flexibility, the @kbd{f} command does @code{forward-sexp} starting
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
356 at point, rather than at the stop point. If you want to execute one
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
357 expression @emph{from the current stop point}, first type @kbd{w}, to
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 move point there, and then type @kbd{f}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 The @kbd{o} command continues ``out of'' an expression. It places a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 temporary breakpoint at the end of the sexp containing point. If the
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
362 containing sexp is a function definition itself, @kbd{o} continues until
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
363 just before the last sexp in the definition. If that is where you are
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
364 now, it returns from the function and then stops. In other words, this
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 command does not exit the currently executing function unless you are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 positioned after the last sexp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 The @kbd{i} command steps into the function or macro called by the list
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
369 form after point, and stops at its first stop point. Note that the form
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
370 need not be the one about to be evaluated. But if the form is a
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
371 function call about to be evaluated, remember to use this command before
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
372 any of the arguments are evaluated, since otherwise it will be too late.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 The @kbd{i} command instruments the function or macro it's supposed to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 step into, if it isn't instrumented already. This is convenient, but keep
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 in mind that the function or macro remains instrumented unless you explicitly
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 arrange to deinstrument it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 @node Edebug Misc
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 @subsection Miscellaneous Edebug Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 Some miscellaneous Edebug commands are described here.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @item ?
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 Display the help message for Edebug (@code{edebug-help}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @item C-]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 Abort one level back to the previous command level
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 (@code{abort-recursive-edit}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @item q
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 Return to the top level editor command loop (@code{top-level}). This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 exits all recursive editing levels, including all levels of Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 activity. However, instrumented code protected with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 @code{unwind-protect} or @code{condition-case} forms may resume
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 debugging.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @item Q
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
400 Like @kbd{q}, but don't stop even for protected code
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 (@code{top-level-nonstop}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @item r
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 Redisplay the most recently known expression result in the echo area
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 (@code{edebug-previous-result}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @item d
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 Display a backtrace, excluding Edebug's own functions for clarity
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 (@code{edebug-backtrace}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 You cannot use debugger commands in the backtrace buffer in Edebug as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 you would in the standard debugger.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 The backtrace buffer is killed automatically when you continue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
418 You can invoke commands from Edebug that activate Edebug again
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
419 recursively. Whenever Edebug is active, you can quit to the top level
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
420 with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
421 display a backtrace of all the pending evaluations with @kbd{d}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
423 @node Breaks
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
424 @subsection Breaks
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
426 Edebug's step mode stops execution when the next stop point is reached.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 There are three other ways to stop Edebug execution once it has started:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 breakpoints, the global break condition, and source breakpoints.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
430 @menu
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
431 * Breakpoints:: Breakpoints at stop points.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
432 * Global Break Condition:: Breaking on an event.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
433 * Source Breakpoints:: Embedding breakpoints in source code.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
434 @end menu
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
435
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
436 @node Breakpoints
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
437 @subsubsection Edebug Breakpoints
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
438
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
439 @cindex breakpoints (Edebug)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 While using Edebug, you can specify @dfn{breakpoints} in the program you
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
441 are testing: these are places where execution should stop. You can set a
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 breakpoint at any stop point, as defined in @ref{Using Edebug}. For
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 setting and unsetting breakpoints, the stop point that is affected is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 the first one at or after point in the source code buffer. Here are the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 Edebug commands for breakpoints:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 @item b
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 Set a breakpoint at the stop point at or after point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 (@code{edebug-set-breakpoint}). If you use a prefix argument, the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
451 breakpoint is temporary---it turns off the first time it stops the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
452 program.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @item u
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
455 Unset the breakpoint (if any) at the stop point at or after
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 point (@code{edebug-unset-breakpoint}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @item x @var{condition} @key{RET}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 Set a conditional breakpoint which stops the program only if
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
460 evaluating @var{condition} produces a non-@code{nil} value
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
461 (@code{edebug-set-conditional-breakpoint}). With a prefix argument,
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
462 the breakpoint is temporary.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @item B
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
465 Move point to the next breakpoint in the current definition
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 (@code{edebug-next-breakpoint}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 While in Edebug, you can set a breakpoint with @kbd{b} and unset one
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 with @kbd{u}. First move point to the Edebug stop point of your choice,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 Unsetting a breakpoint where none has been set has no effect.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
474 Re-evaluating or reinstrumenting a definition removes all of its
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
475 previous breakpoints.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 A @dfn{conditional breakpoint} tests a condition each time the program
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 gets there. Any errors that occur as a result of evaluating the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 condition are ignored, as if the result were @code{nil}. To set a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 conditional breakpoint, use @kbd{x}, and specify the condition
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 expression in the minibuffer. Setting a conditional breakpoint at a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 stop point that has a previously established conditional breakpoint puts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 the previous condition expression in the minibuffer so you can edit it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 You can make a conditional or unconditional breakpoint
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
486 @dfn{temporary} by using a prefix argument with the command to set the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 breakpoint. When a temporary breakpoint stops the program, it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 automatically unset.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
490 Edebug always stops or pauses at a breakpoint, except when the Edebug
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 To find out where your breakpoints are, use the @kbd{B} command, which
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
494 moves point to the next breakpoint following point, within the same
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
495 function, or to the first breakpoint if there are no following
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
496 breakpoints. This command does not continue execution---it just moves
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
497 point in the buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @node Global Break Condition
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 @subsubsection Global Break Condition
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @cindex stopping on events
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 @cindex global break condition
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 A @dfn{global break condition} stops execution when a specified
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 condition is satisfied, no matter where that may occur. Edebug
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
506 evaluates the global break condition at every stop point; if it
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 evaluates to a non-@code{nil} value, then execution stops or pauses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 depending on the execution mode, as if a breakpoint had been hit. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 evaluating the condition gets an error, execution does not stop.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 @findex edebug-set-global-break-condition
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
512 The condition expression is stored in
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
513 @code{edebug-global-break-condition}. You can specify a new expression
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
514 using the @kbd{X} command from the source code buffer while Edebug is
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
515 active, or using @kbd{C-x X X} from any buffer at any time, as long as
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
516 Edebug is loaded (@code{edebug-set-global-break-condition}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 The global break condition is the simplest way to find where in your
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 code some event occurs, but it makes code run much more slowly. So you
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 should reset the condition to @code{nil} when not using it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 @node Source Breakpoints
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 @subsubsection Source Breakpoints
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @findex edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 @cindex source breakpoints
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 All breakpoints in a definition are forgotten each time you
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
528 reinstrument it. If you wish to make a breakpoint that won't be
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
529 forgotten, you can write a @dfn{source breakpoint}, which is simply a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
530 call to the function @code{edebug} in your source code. You can, of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
531 course, make such a call conditional. For example, in the @code{fac}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
532 function, you can insert the first line as shown below, to stop when the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
533 argument reaches zero:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 (defun fac (n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 (if (= n 0) (edebug))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 (if (< 0 n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 (* n (fac (1- n)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
543 When the @code{fac} definition is instrumented and the function is
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 called, the call to @code{edebug} acts as a breakpoint. Depending on
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 the execution mode, Edebug stops or pauses there.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
547 If no instrumented code is being executed when @code{edebug} is called,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 that function calls @code{debug}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @c This may not be a good idea anymore.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @node Trapping Errors
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 @subsection Trapping Errors
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
554 Emacs normally displays an error message when an error is signaled and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
555 not handled with @code{condition-case}. While Edebug is active and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
556 executing instrumented code, it normally responds to all unhandled
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
557 errors. You can customize this with the options @code{edebug-on-error}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
558 and @code{edebug-on-quit}; see @ref{Edebug Options}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
560 When Edebug responds to an error, it shows the last stop point
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 encountered before the error. This may be the location of a call to a
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
562 function which was not instrumented, and within which the error actually
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 occurred. For an unbound variable error, the last known stop point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 might be quite distant from the offending variable reference. In that
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
565 case, you might want to display a full backtrace (@pxref{Edebug Misc}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
567 @c Edebug should be changed for the following: -- dan
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
568 If you change @code{debug-on-error} or @code{debug-on-quit} while
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 Edebug is active, these changes will be forgotten when Edebug becomes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 inactive. Furthermore, during Edebug's recursive edit, these variables
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 are bound to the values they had outside of Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @node Edebug Views
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 @subsection Edebug Views
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
576 These Edebug commands let you view aspects of the buffer and window
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
577 status as they were before entry to Edebug. The outside window
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
578 configuration is the collection of windows and contents that were in
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
579 effect outside of Edebug.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 @item v
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
583 Switch to viewing the outside window configuration
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
584 (@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @item p
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
587 Temporarily display the outside current buffer with point at its
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
588 outside position (@code{edebug-bounce-point}), pausing for one second
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
589 before returning to Edebug. With a prefix argument @var{n}, pause for
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
590 @var{n} seconds instead.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @item w
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
593 Move point back to the current stop point in the source code buffer
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
594 (@code{edebug-where}).
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
595
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
596 If you use this command in a different window displaying the same
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
597 buffer, that window will be used instead to display the current
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
598 definition in the future.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 @item W
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
601 @c Its function is not simply to forget the saved configuration -- dan
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
602 Toggle whether Edebug saves and restores the outside window
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
603 configuration (@code{edebug-toggle-save-windows}).
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
604
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
605 With a prefix argument, @code{W} only toggles saving and restoring of
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
606 the selected window. To specify a window that is not displaying the
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
607 source code buffer, you must use @kbd{C-x X W} from the global keymap.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
610 You can view the outside window configuration with @kbd{v} or just
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 bounce to the point in the current buffer with @kbd{p}, even if
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
612 it is not normally displayed.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
613
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
614 After moving point, you may wish to jump back to the stop point.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
615 You can do that with @kbd{w} from a source code buffer. You can jump
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
616 back to the stop point in the source code buffer from any buffer using
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
617 @kbd{C-x X w}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
619 Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
620 saved outside window configuration---so that even if you turn saving
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
621 back @emph{on}, the current window configuration remains unchanged when
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
622 you next exit Edebug (by continuing the program). However, the
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
623 automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
624 conflict with the buffers you wish to see unless you have enough windows
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
625 open.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @node Edebug Eval
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 @subsection Evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
630 While within Edebug, you can evaluate expressions ``as if'' Edebug
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
631 were not running. Edebug tries to be invisible to the expression's
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 evaluation and printing. Evaluation of expressions that cause side
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
633 effects will work as expected, except for changes to data that Edebug
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
634 explicitly saves and restores. @xref{The Outside Context}, for details
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
635 on this process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @item e @var{exp} @key{RET}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 Evaluate expression @var{exp} in the context outside of Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 (@code{edebug-eval-expression}). That is, Edebug tries to minimize its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 interference with the evaluation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
643 @item M-: @var{exp} @key{RET}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 Evaluate expression @var{exp} in the context of Edebug itself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @item C-x C-e
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 Evaluate the expression before point, in the context outside of Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 (@code{edebug-eval-last-sexp}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 @cindex lexical binding (Edebug)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
652 Edebug supports evaluation of expressions containing references to
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 lexically bound symbols created by the following constructs in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @file{cl.el} (version 2.03 or later): @code{lexical-let},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 @code{macrolet}, and @code{symbol-macrolet}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 @node Eval List
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 @subsection Evaluation List Buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
660 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 evaluate expressions interactively. You can also set up the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 @dfn{evaluation list} of expressions to be evaluated automatically each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 time Edebug updates the display.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 @item E
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 Switch to the evaluation list buffer @samp{*edebug*}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 (@code{edebug-visit-eval-list}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
671 In the @samp{*edebug*} buffer you can use the commands of Lisp
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 Manual}) as well as these special commands:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @table @kbd
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
676 @item C-j
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 Evaluate the expression before point, in the outside context, and insert
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 the value in the buffer (@code{edebug-eval-print-last-sexp}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 @item C-x C-e
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 Evaluate the expression before point, in the context outside of Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 (@code{edebug-eval-last-sexp}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 @item C-c C-u
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
685 Build a new evaluation list from the contents of the buffer
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 (@code{edebug-update-eval-list}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @item C-c C-d
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 Delete the evaluation list group that point is in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 (@code{edebug-delete-eval-item}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @item C-c C-w
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 Switch back to the source code buffer at the current stop point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 (@code{edebug-where}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
697 You can evaluate expressions in the evaluation list window with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
698 @kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 but they are evaluated in the context outside of Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
701 The expressions you enter interactively (and their results) are lost
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 when you continue execution; but you can set up an @dfn{evaluation list}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
703 consisting of expressions to be evaluated each time execution stops.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 @cindex evaluation list group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
706 To do this, write one or more @dfn{evaluation list groups} in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 evaluation list buffer. An evaluation list group consists of one or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 more Lisp expressions. Groups are separated by comment lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
710 The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 evaluation list, scanning the buffer and using the first expression of
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
712 each group. (The idea is that the second expression of the group is the
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
713 value previously computed and displayed.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
715 Each entry to Edebug redisplays the evaluation list by inserting each
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
716 expression in the buffer, followed by its current value. It also
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
717 inserts comment lines so that each expression becomes its own group.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
718 Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
719 the evaluation list is effectively unchanged.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
721 If an error occurs during an evaluation from the evaluation list, the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 error message is displayed in a string as if it were the result.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 Therefore, expressions that use variables not currently valid do not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 interrupt your debugging.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
726 Here is an example of what the evaluation list window looks like after
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 several expressions have been added to it:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 (current-buffer)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 #<buffer *scratch*>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 ;---------------------------------------------------------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 (selected-window)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 #<window 16 on *scratch*>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 ;---------------------------------------------------------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 (point)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 196
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 ;---------------------------------------------------------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 bad-var
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 "Symbol's value as variable is void: bad-var"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 ;---------------------------------------------------------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 (recursion-depth)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 0
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 ;---------------------------------------------------------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 this-command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 eval-last-sexp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 ;---------------------------------------------------------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 delete the text for the group and update the evaluation list with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 @kbd{C-c C-u}. To add a new expression to the evaluation list, insert
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
753 the expression at a suitable place, insert a new comment line, then type
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
754 @kbd{C-c C-u}. You need not insert dashes in the comment line---its
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
755 contents don't matter.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 After selecting @samp{*edebug*}, you can return to the source code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 you continue execution, and recreated next time it is needed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761 @node Printing in Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 @subsection Printing in Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @cindex printing (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 @cindex printing circular structures
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 @pindex cust-print
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 If an expression in your program produces a value containing circular
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 list structure, you may get an error when Edebug attempts to print it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 One way to cope with circular structure is to set @code{print-length}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 or @code{print-level} to truncate the printing. Edebug does this for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 you; it binds @code{print-length} and @code{print-level} to 50 if they
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 were @code{nil}. (Actually, the variables @code{edebug-print-length}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 and @code{edebug-print-level} specify the values to use within Edebug.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775 @xref{Output Variables}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
777 @defopt edebug-print-length
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
778 If non-@code{nil}, Edebug binds @code{print-length} to this value while
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
779 printing results. The default value is @code{50}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
780 @end defopt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
781
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
782 @defopt edebug-print-level
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
783 If non-@code{nil}, Edebug binds @code{print-level} to this value while
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
784 printing results. The default value is @code{50}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
785 @end defopt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
786
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 You can also print circular structures and structures that share
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
788 elements more informatively by binding @code{print-circle}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
789 to a non-@code{nil} value.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 Here is an example of code that creates a circular structure:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 (setq a '(x y))
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
795 (setcar a a)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 Custom printing prints this as @samp{Result: #1=(#1# y)}. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 @samp{#1=} notation labels the structure that follows it with the label
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
801 @samp{1}, and the @samp{#1#} notation references the previously labeled
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 structure. This notation is used for any shared elements of lists or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 vectors.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
805 @defopt edebug-print-circle
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
806 If non-@code{nil}, Edebug binds @code{print-circle} to this value while
59876
59d6cfcd4c9a (Printing in Edebug): Fix edebug-print-circle.
Richard M. Stallman <rms@gnu.org>
parents: 54024
diff changeset
807 printing results. The default value is @code{t}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
808 @end defopt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
809
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 Other programs can also use custom printing; see @file{cust-print.el}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 for details.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 @node Trace Buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 @subsection Trace Buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 @cindex trace buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
817 Edebug can record an execution trace, storing it in a buffer named
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 @samp{*edebug-trace*}. This is a log of function calls and returns,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 showing the function names and their arguments and values. To enable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 Making a trace buffer is not the same thing as using trace execution
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 mode (@pxref{Edebug Execution Modes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 When trace recording is enabled, each function entry and exit adds
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
826 lines to the trace buffer. A function entry record consists of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
827 @samp{::::@{}, followed by the function name and argument values. A
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
828 function exit record consists of @samp{::::@}}, followed by the function
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 name and result of the function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 The number of @samp{:}s in an entry shows its recursion depth. You
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 can use the braces in the trace buffer to find the matching beginning or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 end of function calls.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 @findex edebug-print-trace-before
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 @findex edebug-print-trace-after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 You can customize trace recording for function entry and exit by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 redefining the functions @code{edebug-print-trace-before} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 @code{edebug-print-trace-after}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 @defmac edebug-tracing string body@dots{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 This macro requests additional trace information around the execution
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 of the @var{body} forms. The argument @var{string} specifies text
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
844 to put in the trace buffer, after the @samp{@{} or @samp{@}}. All
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
845 the arguments are evaluated, and @code{edebug-tracing} returns the
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
846 value of the last form in @var{body}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 @end defmac
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 @defun edebug-trace format-string &rest format-args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 This function inserts text in the trace buffer. It computes the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 with @code{(apply 'format @var{format-string} @var{format-args})}.
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
852 It also appends a newline to separate entries.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
855 @code{edebug-tracing} and @code{edebug-trace} insert lines in the
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
856 trace buffer whenever they are called, even if Edebug is not active.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
857 Adding text to the trace buffer also scrolls its window to show the last
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
858 lines inserted.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @node Coverage Testing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 @subsection Coverage Testing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
863 @cindex coverage testing (Edebug)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 @cindex frequency counts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 @cindex performance analysis
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
866 Edebug provides rudimentary coverage testing and display of execution
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
867 frequency.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
868
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
869 Coverage testing works by comparing the result of each expression with
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
870 the previous result; each form in the program is considered ``covered''
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
871 if it has returned two different values since you began testing coverage
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
872 in the current Emacs session. Thus, to do coverage testing on your
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
873 program, execute it under various conditions and note whether it behaves
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
874 correctly; Edebug will tell you when you have tried enough different
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
875 conditions that each form has returned two different values.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
876
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
877 Coverage testing makes execution slower, so it is only done if
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
878 @code{edebug-test-coverage} is non-@code{nil}. Frequency counting is
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
879 performed for all execution of an instrumented function, even if the
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
880 execution mode is Go-nonstop, and regardless of whether coverage testing
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
881 is enabled.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
882
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
883 @kindex C-x X =
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
884 @findex edebug-temp-display-freq-count
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
885 Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
886 the coverage information and the frequency counts for a definition.
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
887 Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
888 information temporarily, only until you type another key.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 @deffn Command edebug-display-freq-count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 This command displays the frequency count data for each line of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 current definition.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
894 The frequency counts appear as comment lines after each line of code,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
895 and you can undo all insertions with one @code{undo} command. The
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
896 counts appear under the @samp{(} before an expression or the @samp{)}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
897 after an expression, or on the last character of a variable. To
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
898 simplify the display, a count is not shown if it is equal to the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
899 count of an earlier expression on the same line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 The character @samp{=} following the count for an expression says that
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
902 the expression has returned the same value each time it was evaluated.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
903 In other words, it is not yet ``covered'' for coverage testing purposes.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 To clear the frequency count and coverage data for a definition,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
906 simply reinstrument it with @code{eval-defun}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 For example, after evaluating @code{(fac 5)} with a source
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 the breakpoint is reached, the frequency data looks like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914 (defun fac (n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 (if (= n 0) (edebug))
59876
59d6cfcd4c9a (Printing in Edebug): Fix edebug-print-circle.
Richard M. Stallman <rms@gnu.org>
parents: 54024
diff changeset
916 ;#6 1 = =5
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 (if (< 0 n)
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
918 ;#5 =
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 (* n (fac (1- n)))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
920 ;# 5 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 1))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
922 ;# 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
925 The comment lines show that @code{fac} was called 6 times. The
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
926 first @code{if} statement returned 5 times with the same result each
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 time; the same is true of the condition on the second @code{if}.
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
928 The recursive call of @code{fac} did not return at all.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
931 @node The Outside Context
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 @subsection The Outside Context
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 Edebug tries to be transparent to the program you are debugging, but it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 does not succeed completely. Edebug also tries to be transparent when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 you evaluate expressions with @kbd{e} or with the evaluation list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 buffer, by temporarily restoring the outside context. This section
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 explains precisely what context Edebug restores, and how Edebug fails to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 be completely transparent.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 * Checking Whether to Stop:: When Edebug decides what to do.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 * Edebug Display Update:: When Edebug updates the display.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 * Edebug Recursive Edit:: When Edebug stops execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 @node Checking Whether to Stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948 @subsubsection Checking Whether to Stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
950 Whenever Edebug is entered, it needs to save and restore certain data
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
951 before even deciding whether to make trace information or stop the
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
952 program.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954 @itemize @bullet
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
955 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
957 incremented once to reduce Edebug's impact on the stack. You could,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
958 however, still run out of stack space when using Edebug.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
960 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 The state of keyboard macro execution is saved and restored. While
61985
2afdce105d7a (Checking Whether to Stop): Fix previous change.
Richard M. Stallman <rms@gnu.org>
parents: 61975
diff changeset
962 Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
2afdce105d7a (Checking Whether to Stop): Fix previous change.
Richard M. Stallman <rms@gnu.org>
parents: 61975
diff changeset
963 unless @code{edebug-continue-kbd-macro} is non-@code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 @node Edebug Display Update
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 @subsubsection Edebug Display Update
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
970 @c This paragraph is not filled, because LaLiberte's conversion script
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
971 @c needs an xref to be on just one line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 When Edebug needs to display something (e.g., in trace mode), it saves
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
973 the current window configuration from ``outside'' Edebug
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
974 (@pxref{Window Configurations}). When you exit Edebug (by continuing
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
975 the program), it restores the previous window configuration.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 Emacs redisplays only when it pauses. Usually, when you continue
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
978 execution, the program re-enters Edebug at a breakpoint or after
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
979 stepping, without pausing or reading input in between. In such cases,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 Emacs never gets a chance to redisplay the ``outside'' configuration.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
981 Consequently, what you see is the same window configuration as the last
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
982 time Edebug was active, with no interruption.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 Entry to Edebug for displaying something also saves and restores the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
985 following data (though some of them are deliberately not restored if an
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
986 error or quit signal occurs).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 @itemize @bullet
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
989 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990 @cindex current buffer point and mark (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 Which buffer is current, and the positions of point and the mark in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 current buffer, are saved and restored.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
994 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995 @cindex window configuration (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 The outside window configuration is saved and restored if
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
997 @code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 The window configuration is not restored on error or quit, but the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 outside selected window @emph{is} reselected even on error or quit in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 case a @code{save-excursion} is active. If the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 @code{edebug-save-windows} is a list, only the listed windows are saved
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 and restored.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005 The window start and horizontal scrolling of the source code buffer are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006 not restored, however, so that the display remains coherent within Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 The value of point in each displayed buffer is saved and restored if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 The variables @code{overlay-arrow-position} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014 @code{overlay-arrow-string} are saved and restored. So you can safely
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 invoke Edebug from the recursive edit elsewhere in the same buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1017 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019 the cursor shows up in the window.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 @node Edebug Recursive Edit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023 @subsubsection Edebug Recursive Edit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 When Edebug is entered and actually reads commands from the user, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 saves (and later restores) these additional data:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 The current match data. @xref{Match Data}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @item
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
1033 The variables @code{last-command}, @code{this-command},
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
1034 @code{last-command-char}, @code{last-input-char},
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
1035 @code{last-input-event}, @code{last-command-event},
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
1036 @code{last-event-frame}, @code{last-nonmenu-event}, and
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
1037 @code{track-mouse}. Commands used within Edebug do not affect these
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
1038 variables outside of Edebug.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039
73400
b370cb67304d (Edebug Recursive Edit): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 71995
diff changeset
1040 Executing commands within Edebug can change the key sequence that
b370cb67304d (Edebug Recursive Edit): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 71995
diff changeset
1041 would be returned by @code{this-command-keys}, and there is no way to
b370cb67304d (Edebug Recursive Edit): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 71995
diff changeset
1042 reset the key sequence from Lisp.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1044 Edebug cannot save and restore the value of
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1045 @code{unread-command-events}. Entering Edebug while this variable has a
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1046 nontrivial value can interfere with execution of the program you are
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1047 debugging.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1048
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 Complex commands executed while in Edebug are added to the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 @code{command-history}. In rare cases this can alter execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 Within Edebug, the recursion depth appears one deeper than the recursion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 depth outside Edebug. This is not true of the automatically updated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 evaluation list window.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 @code{standard-output} and @code{standard-input} are bound to @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 by the @code{recursive-edit}, but Edebug temporarily restores them during
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 evaluations.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1063 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 The state of keyboard macro definition is saved and restored. While
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 Edebug is active, @code{defining-kbd-macro} is bound to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 @code{edebug-continue-kbd-macro}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1069 @node Edebug and Macros
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1070 @subsection Edebug and Macros
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1071
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1072 To make Edebug properly instrument expressions that call macros, some
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1073 extra care is needed. This subsection explains the details.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1074
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1075 @menu
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1076 * Instrumenting Macro Calls:: The basic problem.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1077 * Specification List:: How to specify complex patterns of evaluation.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1078 * Backtracking:: What Edebug does when matching fails.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1079 * Specification Examples:: To help understand specifications.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1080 @end menu
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1081
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 @node Instrumenting Macro Calls
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1083 @subsubsection Instrumenting Macro Calls
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1085 When Edebug instruments an expression that calls a Lisp macro, it needs
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1086 additional information about the macro to do the job properly. This is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1087 because there is no a-priori way to tell which subexpressions of the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1088 macro call are forms to be evaluated. (Evaluation may occur explicitly
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1089 in the macro body, or when the resulting expansion is evaluated, or any
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1090 time later.)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1091
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1092 Therefore, you must define an Edebug specification for each macro
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1093 that Edebug will encounter, to explain the format of calls to that
60616
f028c143bfe6 (Instrumenting Macro Calls): Fix typos.
Lute Kamstra <lute@gnu.org>
parents: 60498
diff changeset
1094 macro. To do this, add a @code{debug} declaration to the macro
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1095 definition. Here is a simple example that shows the specification for
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1096 the @code{for} example macro (@pxref{Argument Evaluation}).
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1097
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
1098 @smallexample
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1099 (defmacro for (var from init to final do &rest body)
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1100 "Execute a simple \"for\" loop.
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1101 For example, (for i from 1 to 10 do (print i))."
60772
e6c6bee5ad7f (Instrumenting Macro Calls): Fix another typo.
Lute Kamstra <lute@gnu.org>
parents: 60616
diff changeset
1102 (declare (debug (symbolp "from" form "to" form "do" &rest form)))
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1103 ...)
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63526
diff changeset
1104 @end smallexample
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1105
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1106 The Edebug specification says which parts of a call to the macro are
52142
187f0047b980 (Instrumenting Macro Calls): Don't define `declare' here;
Richard M. Stallman <rms@gnu.org>
parents: 51652
diff changeset
1107 forms to be evaluated. For simple macros, the @var{specification}
187f0047b980 (Instrumenting Macro Calls): Don't define `declare' here;
Richard M. Stallman <rms@gnu.org>
parents: 51652
diff changeset
1108 often looks very similar to the formal argument list of the macro
187f0047b980 (Instrumenting Macro Calls): Don't define `declare' here;
Richard M. Stallman <rms@gnu.org>
parents: 51652
diff changeset
1109 definition, but specifications are much more general than macro
187f0047b980 (Instrumenting Macro Calls): Don't define `declare' here;
Richard M. Stallman <rms@gnu.org>
parents: 51652
diff changeset
1110 arguments. @xref{Defining Macros}, for more explanation of
53592
26d79d579570 (Instrumenting Macro Calls): `declare' is not a special form.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52849
diff changeset
1111 the @code{declare} form.
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1112
52142
187f0047b980 (Instrumenting Macro Calls): Don't define `declare' here;
Richard M. Stallman <rms@gnu.org>
parents: 51652
diff changeset
1113 You can also define an edebug specification for a macro separately
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1114 from the macro definition with @code{def-edebug-spec}. Adding
60616
f028c143bfe6 (Instrumenting Macro Calls): Fix typos.
Lute Kamstra <lute@gnu.org>
parents: 60498
diff changeset
1115 @code{debug} declarations is preferred, and more convenient, for macro
f028c143bfe6 (Instrumenting Macro Calls): Fix typos.
Lute Kamstra <lute@gnu.org>
parents: 60498
diff changeset
1116 definitions in Lisp, but @code{def-edebug-spec} makes it possible to
f028c143bfe6 (Instrumenting Macro Calls): Fix typos.
Lute Kamstra <lute@gnu.org>
parents: 60498
diff changeset
1117 define Edebug specifications for special forms implemented in C.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 @deffn Macro def-edebug-spec macro specification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 Specify which expressions of a call to macro @var{macro} are forms to be
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1121 evaluated. @var{specification} should be the edebug specification.
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1122 Neither argument is evaluated.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1124 The @var{macro} argument can actually be any symbol, not just a macro
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 name.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 Here is a table of the possibilities for @var{specification} and how each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 directs processing of arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130
7734
2d4db32cccd5 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7252
diff changeset
1131 @table @asis
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 @item @code{t}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 All arguments are instrumented for evaluation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 @item @code{0}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 None of the arguments is instrumented.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 @item a symbol
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 The symbol must have an Edebug specification which is used instead.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 This indirection is repeated until another kind of specification is
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1141 found. This allows you to inherit the specification from another macro.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 @item a list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144 The elements of the list describe the types of the arguments of a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 calling form. The possible elements of a specification list are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 described in the following sections.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1149 @vindex edebug-eval-macro-args
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1150 If a macro has no Edebug specification, neither through a @code{debug}
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1151 declaration nor through a @code{def-edebug-spec} call, the variable
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1152 @code{edebug-eval-macro-args} comes into play. If it is @code{nil},
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1153 the default, none of the arguments is instrumented for evaluation.
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1154 If it is non-@code{nil}, all arguments are instrumented.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 @node Specification List
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157 @subsubsection Specification List
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 @cindex Edebug specification list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160 A @dfn{specification list} is required for an Edebug specification if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 some arguments of a macro call are evaluated while others are not. Some
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 elements in a specification list match one or more arguments, but others
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 modify the processing of all following elements. The latter, called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 as @code{&optional}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 A specification list may contain sublists which match arguments that are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168 themselves lists, or it may contain vectors used for grouping. Sublists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 and groups thus subdivide the specification list into a hierarchy of
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1170 levels. Specification keywords apply only to the remainder of the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171 sublist or group they are contained in.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 When a specification list involves alternatives or repetition, matching
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 it against an actual macro call may require backtracking.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 @xref{Backtracking}, for more details.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177 Edebug specifications provide the power of regular expression matching,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 plus some context-free grammar constructs: the matching of sublists with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 balanced parentheses, recursive processing of forms, and recursion via
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 indirect specifications.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 Here's a table of the possible elements of a specification list, with
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1183 their meanings (see @ref{Specification Examples}, for the referenced
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1184 examples):
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 @item sexp
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1188 A single unevaluated Lisp object, which is not instrumented.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1189 @c an "expression" is not necessarily intended for evaluation.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191 @item form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192 A single evaluated expression, which is instrumented.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 @item place
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 @findex edebug-unwrap
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196 A place to store a value, as in the Common Lisp @code{setf} construct.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 @item body
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 Short for @code{&rest form}. See @code{&rest} below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201 @item function-form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 A function form: either a quoted function symbol, a quoted lambda
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203 expression, or a form (that should evaluate to a function symbol or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204 lambda expression). This is useful when an argument that's a lambda
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 expression might be quoted with @code{quote} rather than
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206 @code{function}, since it instruments the body of the lambda expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 either way.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 @item lambda-expr
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 A lambda expression with no quoting.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 @item &optional
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1213 @c @kindex &optional @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 All following elements in the specification list are optional; as soon
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1215 as one does not match, Edebug stops matching at this level.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 To make just a few elements optional followed by non-optional elements,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 use @code{[&optional @var{specs}@dots{}]}. To specify that several
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 elements must all match or none, use @code{&optional
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1220 [@var{specs}@dots{}]}. See the @code{defun} example.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222 @item &rest
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1223 @c @kindex &rest @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 All following elements in the specification list are repeated zero or
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1225 more times. In the last repetition, however, it is not a problem if the
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1226 expression runs out before matching all of the elements of the
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1227 specification list.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 To specify several elements that must all match on every repetition, use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 @code{&rest [@var{specs}@dots{}]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 @item &or
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1234 @c @kindex &or @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 Each of the following elements in the specification list is an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236 alternative. One of the alternatives must match, or the @code{&or}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237 specification fails.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 Each list element following @code{&or} is a single alternative. To
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 group two or more list elements as a single alternative, enclose them in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 @code{[@dots{}]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 @item &not
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1244 @c @kindex &not @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245 Each of the following elements is matched as alternatives as if by using
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 @code{&or}, but if any of them match, the specification fails. If none
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 of them match, nothing is matched, but the @code{&not} specification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 succeeds.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1250 @item &define
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1251 @c @kindex &define @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 Indicates that the specification is for a defining form. The defining
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1253 form itself is not instrumented (that is, Edebug does not stop before and
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 after the defining form), but forms inside it typically will be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 instrumented. The @code{&define} keyword should be the first element in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 a list specification.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1258 @item nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1259 This is successful when there are no more arguments to match at the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1260 current argument list level; otherwise it fails. See sublist
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1261 specifications and the backquote example.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 @item gate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 @cindex preventing backtracking
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 No argument is matched but backtracking through the gate is disabled
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 while matching the remainder of the specifications at this level. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 is primarily used to generate more specific syntax error messages. See
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1268 @ref{Backtracking}, for more details. Also see the @code{let} example.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 @item @var{other-symbol}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271 @cindex indirect specifications
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 Any other symbol in a specification list may be a predicate or an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273 indirect specification.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275 If the symbol has an Edebug specification, this @dfn{indirect
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276 specification} should be either a list specification that is used in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 place of the symbol, or a function that is called to process the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 arguments. The specification may be defined with @code{def-edebug-spec}
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1279 just as for macros. See the @code{defun} example.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1280
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1281 Otherwise, the symbol should be a predicate. The predicate is called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1282 with the argument and the specification fails if the predicate returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1283 @code{nil}. In either case, that argument is not instrumented.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1284
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1285 Some suitable predicates include @code{symbolp}, @code{integerp},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1286 @code{stringp}, @code{vectorp}, and @code{atom}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1287
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288 @item [@var{elements}@dots{}]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289 @cindex [@dots{}] (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290 A vector of elements groups the elements into a single @dfn{group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 specification}. Its meaning has nothing to do with vectors.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1293 @item "@var{string}"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294 The argument should be a symbol named @var{string}. This specification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1296 of @var{symbol} is the @var{string}, but the string form is preferred.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1297
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 @item (vector @var{elements}@dots{})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299 The argument should be a vector whose elements must match the
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1300 @var{elements} in the specification. See the backquote example.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1301
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302 @item (@var{elements}@dots{})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1303 Any other list is a @dfn{sublist specification} and the argument must be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1304 a list whose elements match the specification @var{elements}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1305
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1306 @cindex dotted lists (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307 A sublist specification may be a dotted list and the corresponding list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 dotted list specification may be another sublist specification (via a
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1310 grouping or an indirect specification, e.g., @code{(spec . [(more
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 specs@dots{})])}) whose elements match the non-dotted list arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312 This is useful in recursive specifications such as in the backquote
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1313 example. Also see the description of a @code{nil} specification
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314 above for terminating such recursion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1316 Note that a sublist specification written as @code{(specs . nil)}
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1317 is equivalent to @code{(specs)}, and @code{(specs .
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1318 (sublist-elements@dots{}))} is equivalent to @code{(specs
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319 sublist-elements@dots{})}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 @c Need to document extensions with &symbol and :symbol
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1324 Here is a list of additional specifications that may appear only after
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1325 @code{&define}. See the @code{defun} example.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1327 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1328 @item name
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1329 The argument, a symbol, is the name of the defining form.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 A defining form is not required to have a name field; and it may have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 multiple name fields.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 @item :name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 This construct does not actually match an argument. The element
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1336 following @code{:name} should be a symbol; it is used as an additional
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1337 name component for the definition. You can use this to add a unique,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338 static component to the name of the definition. It may be used more
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339 than once.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341 @item arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 The argument, a symbol, is the name of an argument of the defining form.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1343 However, lambda-list keywords (symbols starting with @samp{&})
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1344 are not allowed.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 @item lambda-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347 @cindex lambda-list (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 This matches a lambda list---the argument list of a lambda expression.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350 @item def-body
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1351 The argument is the body of code in a definition. This is like
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1352 @code{body}, described above, but a definition body must be instrumented
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 with a different Edebug call that looks up information associated with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 the definition. Use @code{def-body} for the highest level list of forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 within the definition.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357 @item def-form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 The argument is a single, highest-level form in a definition. This is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359 like @code{def-body}, except use this to match a single form rather than
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360 a list of forms. As a special case, @code{def-form} also means that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361 tracing information is not output when the form is executed. See the
63526
80bd8eddac37 (Instrumenting): Eliminate duplicate link.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63452
diff changeset
1362 @code{interactive} example.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 @node Backtracking
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1366 @subsubsection Backtracking in Specifications
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368 @cindex backtracking
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369 @cindex syntax error (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370 If a specification fails to match at some point, this does not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 necessarily mean a syntax error will be signaled; instead,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 @dfn{backtracking} will take place until all alternatives have been
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 exhausted. Eventually every element of the argument list must be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374 matched by some element in the specification, and every required element
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 in the specification must match some argument.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1376
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1377 When a syntax error is detected, it might not be reported until much
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1378 later after higher-level alternatives have been exhausted, and with the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1379 point positioned further from the real error. But if backtracking is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1380 disabled when an error occurs, it can be reported immediately. Note
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1381 that backtracking is also reenabled automatically in several situations;
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1382 it is reenabled when a new alternative is established by
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1383 @code{&optional}, @code{&rest}, or @code{&or}, or at the start of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1384 processing a sublist, group, or indirect specification. The effect of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1385 enabling or disabling backtracking is limited to the remainder of the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1386 level currently being processed and lower levels.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1387
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1388 Backtracking is disabled while matching any of the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1389 form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390 @code{def-body}). These specifications will match any form so any error
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1391 must be in the form itself rather than at a higher level.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1392
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1393 Backtracking is also disabled after successfully matching a quoted
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1394 symbol or string specification, since this usually indicates a
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1395 recognized construct. But if you have a set of alternative constructs that
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1396 all begin with the same symbol, you can usually work around this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397 constraint by factoring the symbol out of the alternatives, e.g.,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398 @code{["foo" &or [first case] [second case] ...]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1399
53595
7ea1b7196d49 *** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents: 53592
diff changeset
1400 Most needs are satisfied by these two ways that backtracking is
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1401 automatically disabled, but occasionally it is useful to explicitly
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1402 disable backtracking by using the @code{gate} specification. This is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1403 useful when you know that no higher alternatives could apply. See the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1404 example of the @code{let} specification.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 @node Specification Examples
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 @subsubsection Specification Examples
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 It may be easier to understand Edebug specifications by studying
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 the examples provided here.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 A @code{let} special form has a sequence of bindings and a body. Each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413 of the bindings is either a symbol or a sublist with a symbol and
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1414 optional expression. In the specification below, notice the @code{gate}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415 inside of the sublist to prevent backtracking once a sublist is found.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1416
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 (def-edebug-spec let
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 ((&rest
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420 &or symbolp (gate symbolp &optional form))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421 body))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 Edebug uses the following specifications for @code{defun} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1425 @code{defmacro} and the associated argument list and @code{interactive}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426 specifications. It is necessary to handle interactive forms specially
63452
35fe0bb36962 (Edebug): Update menu.
Luc Teirlinck <teirllm@auburn.edu>
parents: 61985
diff changeset
1427 since an expression argument is actually evaluated outside of the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428 function body.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1430 @smallexample
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1431 (def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1432 (def-edebug-spec defun
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1433 (&define name lambda-list
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1434 [&optional stringp] ; @r{Match the doc string, if present.}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1435 [&optional ("interactive" interactive)]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1436 def-body))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1437
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1438 (def-edebug-spec lambda-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1439 (([&rest arg]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440 [&optional ["&optional" arg &rest arg]]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 &optional ["&rest" arg]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 )))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 (def-edebug-spec interactive
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1446 @end smallexample
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448 The specification for backquote below illustrates how to match
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449 dotted lists and use @code{nil} to terminate recursion. It also
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450 illustrates how components of a vector may be matched. (The actual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451 specification defined by Edebug does not support dotted lists because
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452 doing so causes very deep recursion that could fail.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1454 @smallexample
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1455 (def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 (def-edebug-spec backquote-form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458 (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 (backquote-form . [&or nil backquote-form])
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 (vector &rest backquote-form)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461 sexp))
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1462 @end smallexample
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @node Edebug Options
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466 @subsection Edebug Options
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 These options affect the behavior of Edebug:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 @defopt edebug-setup-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 Functions to call before Edebug is used. Each time it is set to a new
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472 value, Edebug will call those functions once and then
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 @code{edebug-setup-hook} is reset to @code{nil}. You could use this to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 load up Edebug specifications associated with a package you are using
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 but only when you also use Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 @xref{Instrumenting}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 @defopt edebug-all-defs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480 If this is non-@code{nil}, normal evaluation of defining forms such as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481 @code{defun} and @code{defmacro} instruments them for Edebug. This
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1482 applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1483 and @code{eval-current-buffer}.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1484
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1485 Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1486 option. @xref{Instrumenting}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1489 @defopt edebug-all-forms
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1490 If this is non-@code{nil}, the commands @code{eval-defun},
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1491 @code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1492 instrument all forms, even those that don't define anything.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1493 This doesn't apply to loading or evaluations in the minibuffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1496 option. @xref{Instrumenting}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1498
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1499 @defopt edebug-save-windows
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 If this is non-@code{nil}, Edebug saves and restores the window
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1501 configuration. That takes some time, so if your program does not care
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1502 what happens to the window configurations, it is better to set this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1503 variable to @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1504
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 If the value is a list, only the listed windows are saved and
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1506 restored.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508 You can use the @kbd{W} command in Edebug to change this variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1509 interactively. @xref{Edebug Display Update}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 @defopt edebug-save-displayed-buffer-points
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1513 If this is non-@code{nil}, Edebug saves and restores point in all
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1514 displayed buffers.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1516 Saving and restoring point in other buffers is necessary if you are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 debugging code that changes the point of a buffer which is displayed in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518 a non-selected window. If Edebug or the user then selects the window,
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1519 point in that buffer will move to the window's value of point.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521 Saving and restoring point in all buffers is expensive, since it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522 requires selecting each window twice, so enable this only if you need
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523 it. @xref{Edebug Display Update}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 @defopt edebug-initial-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1527 If this variable is non-@code{nil}, it specifies the initial execution
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528 mode for Edebug when it is first activated. Possible values are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1529 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1532 The default value is @code{step}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533 @xref{Edebug Execution Modes}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536 @defopt edebug-trace
71995
26c633d614ed fix bad page breaks
Karl Berry <karl@gnu.org>
parents: 71629
diff changeset
1537 If this is non-@code{nil}, trace each function entry and exit.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1539 function entry or exit per line, indented by the recursion level.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1541 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1544 @defopt edebug-test-coverage
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546 @xref{Coverage Testing}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1547 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1549 @defopt edebug-continue-kbd-macro
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550 If non-@code{nil}, continue defining or executing any keyboard macro
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551 that is executing outside of Edebug. Use this with caution since it is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 debugged.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553 @xref{Edebug Execution Modes}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1556 @defopt edebug-on-error
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1557 Edebug binds @code{debug-on-error} to this value, if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1558 @code{debug-on-error} was previously @code{nil}. @xref{Trapping
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559 Errors}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1560 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562 @defopt edebug-on-quit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 Edebug binds @code{debug-on-quit} to this value, if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 @code{debug-on-quit} was previously @code{nil}. @xref{Trapping
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1565 Errors}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1566 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1567
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1568 If you change the values of @code{edebug-on-error} or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1569 @code{edebug-on-quit} while Edebug is active, their values won't be used
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1570 until the @emph{next} time Edebug is invoked via a new command.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1571 @c Not necessarily a deeper command level.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1572 @c A new command is not precisely true, but that is close enough -- dan
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574 @defopt edebug-global-break-condition
51652
55fb0658914a Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
1575 If non-@code{nil}, an expression to test for at every stop point. If
55fb0658914a Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
1576 the result is non-@code{nil}, then break. Errors are ignored.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1577 @xref{Global Break Condition}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 @end defopt
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52142
diff changeset
1579
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52142
diff changeset
1580 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52142
diff changeset
1581 arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52142
diff changeset
1582 @end ignore