annotate lispref/edebug.texi @ 55095:4d5ade635f7a

(char-displayable-p): Simplified by using internal-char-font.
author Kenichi Handa <handa@m17n.org>
date Fri, 23 Apr 2004 02:08:22 +0000
parents 9f3c718e5096
children 59d6cfcd4c9a
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.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
3 @c Copyright (C) 1992, 1993, 1994, 1998, 1999 Free Software Foundation, Inc.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
4 @c See the file elisp.texi for copying conditions.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
6 @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
7 @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
8 @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
9
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @c , Bugs and Todo List, Top, Top
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
12 @node Edebug, Syntax Errors, Debugger, Debugging
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 @section Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 @cindex Edebug mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 @cindex Edebug
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.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 * Breakpoints:: 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.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 * Instrumenting Macro Calls:: Specifying how to handle macro calls.
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
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 An arrow at the left margin indicates the line where the function is
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)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 Once you have loaded Edebug, the command @kbd{C-M-x}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 (@code{eval-defun}) is redefined so that when invoked with a prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 argument on a definition, it instruments the definition before
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 evaluating it. (The source code itself is not modified.) If the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 variable @code{edebug-all-defs} is non-@code{nil}, that inverts the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
166 meaning of the prefix argument: in this case, @kbd{C-M-x} instruments the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 definition @emph{unless} it has a prefix argument. The default value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 @code{edebug-all-defs} is @code{nil}. The command @kbd{M-x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 edebug-all-defs} toggles the value of the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 @code{edebug-all-defs}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
172 @findex eval-region @r{(Edebug)}
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
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 @cindex special forms (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @cindex interactive commands (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 @cindex anonymous lambda expressions (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 @cindex Common Lisp (Edebug)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
201 @pindex cl.el @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 @pindex cl-specs.el
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
203 Edebug knows how to instrument all the standard special forms,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
204 @code{interactive} forms with an expression argument, anonymous lambda
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
205 expressions, and other defining forms. However, Edebug cannot determine
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
206 on its own what a user-defined macro will do with the arguments of a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
207 macro call, so you must provide that information; see @ref{Instrumenting
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
208 Macro Calls}, for details.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
210 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
211 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
212 @code{nil}. You can use this to load Edebug specifications
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
213 (@pxref{Instrumenting Macro Calls}) associated with a package you are
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
214 using, but only when you use Edebug.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
215
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
216 @findex eval-expression @r{(Edebug)}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
217 To remove instrumentation from a definition, simply re-evaluate its
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 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
219 evaluating forms that never instrument them: from a file with
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 @code{load}, and from the minibuffer with @code{eval-expression}
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
221 (@kbd{M-:}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 If Edebug detects a syntax error while instrumenting, it leaves point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 at the erroneous code and signals an @code{invalid-read-syntax} error.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @xref{Edebug Eval}, for other evaluation functions available
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 inside of Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @node Edebug Execution Modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @subsection Edebug Execution Modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 @cindex Edebug execution modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 Edebug supports several execution modes for running the program you are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 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
235 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
236 determines how far Edebug continues execution before stopping---whether
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 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
238 example---and how much Edebug displays the progress of the evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 before it stops.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 Normally, you specify the Edebug execution mode by typing a command to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 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
243 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
244 least for a certain distance.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @item S
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
248 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
249 Edebug commands (@code{edebug-stop}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @item @key{SPC}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @item n
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 Next: stop at the next stop point encountered after an expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 @ref{Edebug Misc}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @item t
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
260 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
261 (@code{edebug-trace-mode}).
6558
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 T
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 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
265 pause (@code{edebug-Trace-fast-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 g
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @item c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 Continue: pause one second at each breakpoint, and then continue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 (@code{edebug-continue-mode}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 @item C
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 Rapid continue: move point to each breakpoint, but don't pause
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 (@code{edebug-Continue-fast-mode}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @item G
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 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
281 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 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
284 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
285
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 While executing or tracing, you can interrupt the execution by typing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 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
288 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
289 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
290 @kbd{S} to stop execution without doing anything else.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 If your function happens to read input, a character you type intending
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 to interrupt execution may be read by the function instead. You can
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 avoid such unintended results by paying attention to when your program
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 wants input.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @cindex keyboard macros (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 Keyboard macros containing the commands in this section do not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 completely work: exiting from Edebug, to resume the program, loses track
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 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
301 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
302 inside Edebug. This is usually an advantage. See also the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 @code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 When you enter a new Edebug level, the initial execution mode comes from
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 the value of the variable @code{edebug-initial-mode}. By default, this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 specifies step mode. Note that you may reenter the same Edebug level
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 several times if, for example, an instrumented function is called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 several times from one command.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
311 @defopt edebug-sit-for-seconds
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
312 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
313 in trace mode. The default is 1 second.
52849
3e34838fbfac Fix typo.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52840
diff changeset
314 @end defopt
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @node Jumping
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @subsection Jumping
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 The commands described in this section execute until they reach a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 specified location. All except @kbd{i} make a temporary breakpoint to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 establish the place to stop, then switch to go mode. Any other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 breakpoint reached before the intended stop point will also stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 execution. @xref{Breakpoints}, for the details on breakpoints.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 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
326 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
327 program to stop.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 @item h
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 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
332
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 @item f
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 Run the program forward over one expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 (@code{edebug-forward-sexp}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @item o
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 Run the program until the end of the containing sexp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 @item i
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 Step into the function or macro called by the form after point.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 The @kbd{h} command proceeds to the stop point near the current location
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
345 of point, using a temporary breakpoint. See @ref{Breakpoints}, for more
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
346 information about breakpoints.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 The @kbd{f} command runs the program forward over one expression. More
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 precisely, it sets a temporary breakpoint at the position that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @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
351 will stop at breakpoints.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 With a prefix argument @var{n}, the temporary breakpoint is placed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @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
355 more elements, then the place to stop is after the containing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 expression.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
358 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
359 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
360 be true.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
362 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
363 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
364 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
365 move point there, and then type @kbd{f}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 The @kbd{o} command continues ``out of'' an expression. It places a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 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
369 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
370 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
371 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
372 command does not exit the currently executing function unless you are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 positioned after the last sexp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 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
376 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
377 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
378 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
379 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
380
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 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
382 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
383 in mind that the function or macro remains instrumented unless you explicitly
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 arrange to deinstrument it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 @node Edebug Misc
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 @subsection Miscellaneous Edebug Commands
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 Some miscellaneous Edebug commands are described here.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @item ?
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 Display the help message for Edebug (@code{edebug-help}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 @item C-]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 Abort one level back to the previous command level
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 (@code{abort-recursive-edit}).
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
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 Return to the top level editor command loop (@code{top-level}). This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 exits all recursive editing levels, including all levels of Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 activity. However, instrumented code protected with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @code{unwind-protect} or @code{condition-case} forms may resume
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 debugging.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 @item Q
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
407 Like @kbd{q}, but don't stop even for protected code
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 (@code{top-level-nonstop}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 @item r
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 Redisplay the most recently known expression result in the echo area
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 (@code{edebug-previous-result}).
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 @item d
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 Display a backtrace, excluding Edebug's own functions for clarity
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 (@code{edebug-backtrace}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 You cannot use debugger commands in the backtrace buffer in Edebug as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 you would in the standard debugger.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 The backtrace buffer is killed automatically when you continue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
425 You can invoke commands from Edebug that activate Edebug again
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
426 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
427 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
428 display a backtrace of all the pending evaluations with @kbd{d}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 @node Breakpoints
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @subsection Breakpoints
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 @cindex breakpoints
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
434 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
435 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
436 breakpoints, the global break condition, and source breakpoints.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 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
439 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
440 breakpoint at any stop point, as defined in @ref{Using Edebug}. For
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 setting and unsetting breakpoints, the stop point that is affected is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 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
443 Edebug commands for breakpoints:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @item b
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 Set a breakpoint at the stop point at or after point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 (@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
449 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
450 program.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 @item u
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
453 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
454 point (@code{edebug-unset-breakpoint}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @item x @var{condition} @key{RET}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 Set a conditional breakpoint which stops the program only if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @var{condition} evaluates to a non-@code{nil} value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 (@code{edebug-set-conditional-breakpoint}). With a prefix argument, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 breakpoint is temporary.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @item B
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
463 Move point to the next breakpoint in the current definition
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 (@code{edebug-next-breakpoint}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 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
468 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
469 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
470 Unsetting a breakpoint where none has been set has no effect.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
472 Re-evaluating or reinstrumenting a definition removes all of its
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
473 previous breakpoints.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 A @dfn{conditional breakpoint} tests a condition each time the program
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 gets there. Any errors that occur as a result of evaluating the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 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
478 conditional breakpoint, use @kbd{x}, and specify the condition
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 expression in the minibuffer. Setting a conditional breakpoint at a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 stop point that has a previously established conditional breakpoint puts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 the previous condition expression in the minibuffer so you can edit it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 You can make a conditional or unconditional breakpoint
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
484 @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
485 breakpoint. When a temporary breakpoint stops the program, it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 automatically unset.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
488 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
489 mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 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
492 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
493 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
494 breakpoints. This command does not continue execution---it just moves
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
495 point in the buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 @menu
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
498 * Global Break Condition:: Breaking on an event.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 * Source Breakpoints:: Embedding breakpoints in source code.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 @end menu
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
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 @node Global Break Condition
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 @subsubsection Global Break Condition
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 @cindex stopping on events
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 @cindex global break condition
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 A @dfn{global break condition} stops execution when a specified
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 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
510 evaluates the global break condition at every stop point; if it
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 evaluates to a non-@code{nil} value, then execution stops or pauses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 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
513 evaluating the condition gets an error, execution does not stop.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 @findex edebug-set-global-break-condition
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
516 The condition expression is stored in
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
517 @code{edebug-global-break-condition}. You can specify a new expression
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
518 using the @kbd{X} command (@code{edebug-set-global-break-condition}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 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
521 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
522 should reset the condition to @code{nil} when not using it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 @node Source Breakpoints
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @subsubsection Source Breakpoints
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 @findex edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 @cindex source breakpoints
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 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
530 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
531 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
532 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
533 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
534 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
535 argument reaches zero:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 (defun fac (n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 (if (= n 0) (edebug))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 (if (< 0 n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 (* n (fac (1- n)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
545 When the @code{fac} definition is instrumented and the function is
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 called, the call to @code{edebug} acts as a breakpoint. Depending on
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 the execution mode, Edebug stops or pauses there.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
549 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
550 that function calls @code{debug}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @c This may not be a good idea anymore.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @node Trapping Errors
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 @subsection Trapping Errors
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
556 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
557 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
558 executing instrumented code, it normally responds to all unhandled
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
559 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
560 and @code{edebug-on-quit}; see @ref{Edebug Options}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
562 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
563 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
564 function which was not instrumented, and within which the error actually
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 occurred. For an unbound variable error, the last known stop point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 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
567 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
568
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
569 @c Edebug should be changed for the following: -- dan
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
570 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
571 Edebug is active, these changes will be forgotten when Edebug becomes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 inactive. Furthermore, during Edebug's recursive edit, these variables
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 are bound to the values they had outside of Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @node Edebug Views
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 @subsection Edebug Views
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
578 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
579 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
580 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
581 effect outside of Edebug.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 @item v
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
585 Temporarily view the outside window configuration
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
586 (@code{edebug-view-outside}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @item p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 Temporarily display the outside current buffer with point at its outside
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 position (@code{edebug-bounce-point}). With a prefix argument @var{n},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 pause for @var{n} seconds instead.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 @item w
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
594 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
595 (@code{edebug-where}).
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
596
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
597 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
598 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
599 definition in the future.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @item W
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
602 @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
603 Toggle whether Edebug saves and restores the outside window
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
604 configuration (@code{edebug-toggle-save-windows}).
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
605
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
606 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
607 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
608 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
609 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
611 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
612 bounce to the point in the current buffer with @kbd{p}, even if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 it is not normally displayed. After moving point, you may wish to jump
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 back to the stop point with @kbd{w} from a source code buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
616 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
617 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
618 back @emph{on}, the current window configuration remains unchanged when
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
619 you next exit Edebug (by continuing the program). However, the
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
620 automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
621 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
622 open.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @node Edebug Eval
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 @subsection Evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
627 While within Edebug, you can evaluate expressions ``as if'' Edebug
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
628 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
629 evaluation and printing. Evaluation of expressions that cause side
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
630 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
631 explicitly saves and restores. @xref{The Outside Context}, for details
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
632 on this process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 @item e @var{exp} @key{RET}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 Evaluate expression @var{exp} in the context outside of Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 (@code{edebug-eval-expression}). That is, Edebug tries to minimize its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 interference with the evaluation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
640 @item M-: @var{exp} @key{RET}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 Evaluate expression @var{exp} in the context of Edebug itself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 @item C-x C-e
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 Evaluate the expression before point, in the context outside of Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 (@code{edebug-eval-last-sexp}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @cindex lexical binding (Edebug)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
649 Edebug supports evaluation of expressions containing references to
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 lexically bound symbols created by the following constructs in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 @file{cl.el} (version 2.03 or later): @code{lexical-let},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 @code{macrolet}, and @code{symbol-macrolet}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @node Eval List
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 @subsection Evaluation List Buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
657 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
658 evaluate expressions interactively. You can also set up the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 @dfn{evaluation list} of expressions to be evaluated automatically each
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 time Edebug updates the display.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 @table @kbd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 @item E
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 Switch to the evaluation list buffer @samp{*edebug*}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 (@code{edebug-visit-eval-list}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
668 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
669 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 Manual}) as well as these special commands:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 @table @kbd
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
673 @item C-j
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 Evaluate the expression before point, in the outside context, and insert
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 the value in the buffer (@code{edebug-eval-print-last-sexp}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 @item C-x C-e
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 Evaluate the expression before point, in the context outside of Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 (@code{edebug-eval-last-sexp}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 @item C-c C-u
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
682 Build a new evaluation list from the contents of the buffer
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 (@code{edebug-update-eval-list}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @item C-c C-d
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 Delete the evaluation list group that point is in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 (@code{edebug-delete-eval-item}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 @item C-c C-w
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 Switch back to the source code buffer at the current stop point
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 (@code{edebug-where}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
694 You can evaluate expressions in the evaluation list window with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
695 @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
696 but they are evaluated in the context outside of Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
698 The expressions you enter interactively (and their results) are lost
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 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
700 consisting of expressions to be evaluated each time execution stops.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 @cindex evaluation list group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
703 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
704 evaluation list buffer. An evaluation list group consists of one or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 more Lisp expressions. Groups are separated by comment lines.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
707 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
708 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
709 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
710 value previously computed and displayed.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
712 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
713 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
714 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
715 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
716 the evaluation list is effectively unchanged.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
718 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
719 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
720 Therefore, expressions that use variables not currently valid do not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 interrupt your debugging.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
723 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
724 several expressions have been added to it:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 (current-buffer)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 #<buffer *scratch*>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 ;---------------------------------------------------------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 (selected-window)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 #<window 16 on *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 (point)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 196
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 bad-var
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 "Symbol's value as variable is void: bad-var"
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 (recursion-depth)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 0
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 this-command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 eval-last-sexp
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 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 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
748 delete the text for the group and update the evaluation list with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 @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
750 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
751 @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
752 contents don't matter.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 After selecting @samp{*edebug*}, you can return to the source code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 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
756 you continue execution, and recreated next time it is needed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 @node Printing in Edebug
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 @subsection Printing in Edebug
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 @cindex printing (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 @cindex printing circular structures
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @pindex cust-print
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 If an expression in your program produces a value containing circular
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 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
766
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 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
768 or @code{print-level} to truncate the printing. Edebug does this for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 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
770 were @code{nil}. (Actually, the variables @code{edebug-print-length}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 and @code{edebug-print-level} specify the values to use within Edebug.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 @xref{Output Variables}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
774 @defopt edebug-print-length
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
775 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
776 printing results. The default value is @code{50}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
777 @end defopt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
778
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
779 @defopt edebug-print-level
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
780 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
781 printing results. The default value is @code{50}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
782 @end defopt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
783
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 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
785 elements more informatively by binding @code{print-circle}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
786 to a non-@code{nil} value.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 Here is an example of code that creates a circular structure:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 (setq a '(x y))
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
792 (setcar a a)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 Custom printing prints this as @samp{Result: #1=(#1# y)}. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 @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
798 @samp{1}, and the @samp{#1#} notation references the previously labeled
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 structure. This notation is used for any shared elements of lists or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 vectors.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
802 @defopt edebug-print-circle
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
803 If non-@code{nil}, Edebug binds @code{print-circle} to this value while
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
804 printing results. The default value is @code{nil}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
805 @end defopt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
806
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807 Other programs can also use custom printing; see @file{cust-print.el}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 for details.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 @node Trace Buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 @subsection Trace Buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 @cindex trace buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
814 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
815 @samp{*edebug-trace*}. This is a log of function calls and returns,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 showing the function names and their arguments and values. To enable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 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
820 mode (@pxref{Edebug Execution Modes}).
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 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
823 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
824 @samp{::::@{}, followed by the function name and argument values. A
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
825 function exit record consists of @samp{::::@}}, followed by the function
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 name and result of the function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 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
829 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
830 end of function calls.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 @findex edebug-print-trace-before
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 @findex edebug-print-trace-after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 You can customize trace recording for function entry and exit by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 redefining the functions @code{edebug-print-trace-before} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 @code{edebug-print-trace-after}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @defmac edebug-tracing string body@dots{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 This macro requests additional trace information around the execution
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 of the @var{body} forms. The argument @var{string} specifies text
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
841 to put in the trace buffer. All the arguments are evaluated, and
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 @code{edebug-tracing} returns the value of the last form in @var{body}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @end defmac
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 @defun edebug-trace format-string &rest format-args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 This function inserts text in the trace buffer. It computes the text
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 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
848 It also appends a newline to separate entries.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
851 @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
852 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
853 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
854 lines inserted.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 @node Coverage Testing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 @subsection Coverage Testing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 @cindex coverage testing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @cindex frequency counts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 @cindex performance analysis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 Edebug provides rudimentary coverage testing and display of execution
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
863 frequency.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
864
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
865 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
866 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
867 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
868 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
869 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
870 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
871 conditions that each form has returned two different values.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
872
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
873 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
874 @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
875 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
876 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
877 is enabled.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
878
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
879 @kindex C-x X =
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
880 @findex edebug-temp-display-freq-count
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
881 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
882 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
883 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
884 information temporarily, only until you type another key.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 @deffn Command edebug-display-freq-count
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 This command displays the frequency count data for each line of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 current definition.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
890 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
891 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
892 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
893 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
894 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
895 count of an earlier expression on the same line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 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
898 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
899 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
900
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 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
902 simply reinstrument it with @code{eval-defun}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @end deffn
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 For example, after evaluating @code{(fac 5)} with a source
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 the breakpoint is reached, the frequency data looks like this:
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 (defun fac (n)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 (if (= n 0) (edebug))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
912 ;#6 1 0 =5
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 (if (< 0 n)
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
914 ;#5 =
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 (* n (fac (1- n)))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
916 ;# 5 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 1))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
918 ;# 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
921 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
922 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
923 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
924 The recursive call of @code{fac} did not return at all.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 @node The Outside Context
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 @subsection The Outside Context
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 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
931 does not succeed completely. Edebug also tries to be transparent when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 you evaluate expressions with @kbd{e} or with the evaluation list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 buffer, by temporarily restoring the outside context. This section
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 explains precisely what context Edebug restores, and how Edebug fails to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 be completely transparent.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 * Checking Whether to Stop:: When Edebug decides what to do.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 * Edebug Display Update:: When Edebug updates the display.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 * Edebug Recursive Edit:: When Edebug stops execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @node Checking Whether to Stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 @subsubsection Checking Whether to Stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
946 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
947 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
948 program.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 @itemize @bullet
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
951 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 @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
953 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
954 however, still run out of stack space when using Edebug.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
956 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 The state of keyboard macro execution is saved and restored. While
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
958 Edebug is active, @code{executing-macro} is bound to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959 @code{edebug-continue-kbd-macro}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 @node Edebug Display Update
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 @subsubsection Edebug Display Update
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
967 @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
968 @c needs an xref to be on just one line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 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
970 the current window configuration from ``outside'' Edebug
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
971 (@pxref{Window Configurations}). When you exit Edebug (by continuing
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
972 the program), it restores the previous window configuration.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 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
975 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
976 stepping, without pausing or reading input in between. In such cases,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 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
978 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
979 time Edebug was active, with no interruption.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 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
982 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
983 error or quit signal occurs).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @itemize @bullet
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
986 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @cindex current buffer point and mark (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 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
989 current buffer, are saved and restored.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
991 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 @cindex window configuration (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 The outside window configuration is saved and restored if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 @code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Display Update}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 The window configuration is not restored on error or quit, but the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 outside selected window @emph{is} reselected even on error or quit in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 case a @code{save-excursion} is active. If the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 @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
1000 and restored.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 The window start and horizontal scrolling of the source code buffer are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 not restored, however, so that the display remains coherent within Edebug.
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 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006 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
1007 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 The variables @code{overlay-arrow-position} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 @code{overlay-arrow-string} are saved and restored. So you can safely
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 invoke Edebug from the recursive edit elsewhere in the same buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1014 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 @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
1016 the cursor shows up in the window.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019 @node Edebug Recursive Edit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 @subsubsection Edebug Recursive Edit
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 When Edebug is entered and actually reads commands from the user, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023 saves (and later restores) these additional data:
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 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 The current match data. @xref{Match Data}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028
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 @code{last-command}, @code{this-command}, @code{last-command-char},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031 @code{last-input-char}, @code{last-input-event},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @code{last-command-event}, @code{last-event-frame},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 @code{last-nonmenu-event}, and @code{track-mouse}. Commands used within
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 Edebug do not affect these variables outside of Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036 The key sequence returned by @code{this-command-keys} is changed by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 executing commands within Edebug and there is no way to reset
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 the key sequence from Lisp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1040 Edebug cannot save and restore the value of
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1041 @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
1042 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
1043 debugging.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1044
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 Complex commands executed while in Edebug are added to the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 @code{command-history}. In rare cases this can alter execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048
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 Within Edebug, the recursion depth appears one deeper than the recursion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 depth outside Edebug. This is not true of the automatically updated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 evaluation list window.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 @code{standard-output} and @code{standard-input} are bound to @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 by the @code{recursive-edit}, but Edebug temporarily restores them during
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 evaluations.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1059 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 The state of keyboard macro definition is saved and restored. While
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 Edebug is active, @code{defining-kbd-macro} is bound to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 @code{edebug-continue-kbd-macro}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 @node Instrumenting Macro Calls
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 @subsection Instrumenting Macro Calls
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1068 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
1069 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
1070 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
1071 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
1072 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
1073 time later.)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1074
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1075 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
1076 that Edebug will encounter, to explain the format of calls to that
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1077 macro. To do this, add an @code{edebug} declaration to the macro
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1078 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
1079 the @code{for} example macro (@pxref{Argument Evaluation}).
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1080
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1081 @example
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1082 (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
1083 "Execute a simple \"for\" loop.
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1084 For example, (for i from 1 to 10 do (print i))."
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1085 (declare (edebug symbolp "from" form "to" form "do" &rest form))
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1086 ...)
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1087 @end example
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1088
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1089 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
1090 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
1091 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
1092 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
1093 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
1094 the @code{declare} form.
44674
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1095
52142
187f0047b980 (Instrumenting Macro Calls): Don't define `declare' here;
Richard M. Stallman <rms@gnu.org>
parents: 51652
diff changeset
1096 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
1097 from the macro definition with @code{def-edebug-spec}. Adding
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1098 @code{edebug} declarations is preferred, and more convenient, for
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1099 macro definitions in Lisp, but @code{def-edebug-spec} makes it
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1100 possible to define Edebug specifications for special forms implemented
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1101 in C.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 @deffn Macro def-edebug-spec macro specification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 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
1105 evaluated. @var{specification} should be the edebug specification.
dc4f42a216d8 Explain use of `declare'.
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1106 It is not evaluated.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1108 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
1109 name.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112 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
1113 directs processing of arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114
7734
2d4db32cccd5 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7252
diff changeset
1115 @table @asis
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 @item @code{t}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117 All arguments are instrumented for evaluation.
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 @item @code{0}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 None of the arguments is instrumented.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 @item a symbol
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 The symbol must have an Edebug specification which is used instead.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 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
1125 found. This allows you to inherit the specification from another macro.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127 @item a list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 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
1129 calling form. The possible elements of a specification list are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 described in the following sections.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 * Specification List:: How to specify complex patterns of evaluation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 * Backtracking:: What Edebug does when matching fails.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 * Specification Examples:: To help understand specifications.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 @node Specification List
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 @subsubsection Specification List
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 @cindex Edebug specification list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144 A @dfn{specification list} is required for an Edebug specification if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 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
1146 elements in a specification list match one or more arguments, but others
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 modify the processing of all following elements. The latter, called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149 as @code{&optional}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 A specification list may contain sublists which match arguments that are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 themselves lists, or it may contain vectors used for grouping. Sublists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 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
1154 levels. Specification keywords apply only to the remainder of the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 sublist or group they are contained in.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157 When a specification list involves alternatives or repetition, matching
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 it against an actual macro call may require backtracking.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 @xref{Backtracking}, for more details.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 Edebug specifications provide the power of regular expression matching,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 plus some context-free grammar constructs: the matching of sublists with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 balanced parentheses, recursive processing of forms, and recursion via
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 indirect specifications.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 Here's a table of the possible elements of a specification list, with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 their meanings:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1170 @item sexp
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1171 A single unevaluated Lisp object, which is not instrumented.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1172 @c an "expression" is not necessarily intended for evaluation.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 @item form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 A single evaluated expression, which is instrumented.
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 @item place
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 @findex edebug-unwrap
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 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
1180
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 @item body
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 Short for @code{&rest form}. See @code{&rest} below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184 @item function-form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 A function form: either a quoted function symbol, a quoted lambda
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186 expression, or a form (that should evaluate to a function symbol or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 lambda expression). This is useful when an argument that's a lambda
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 expression might be quoted with @code{quote} rather than
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 @code{function}, since it instruments the body of the lambda expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190 either way.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192 @item lambda-expr
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 A lambda expression with no quoting.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 @item &optional
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1196 @c @kindex &optional @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 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
1198 as one does not match, Edebug stops matching at this level.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200 To make just a few elements optional followed by non-optional elements,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201 use @code{[&optional @var{specs}@dots{}]}. To specify that several
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 elements must all match or none, use @code{&optional
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203 [@var{specs}@dots{}]}. See the @code{defun} example below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 @item &rest
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1206 @c @kindex &rest @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 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
1208 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
1209 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
1210 specification list.
6558
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 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213 To specify several elements that must all match on every repetition, use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 @code{&rest [@var{specs}@dots{}]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216 @item &or
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1217 @c @kindex &or @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 Each of the following elements in the specification list is an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 alternative. One of the alternatives must match, or the @code{&or}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220 specification fails.
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 Each list element following @code{&or} is a single alternative. To
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 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
1224 @code{[@dots{}]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 @item &not
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1227 @c @kindex &not @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228 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
1229 @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
1230 of them match, nothing is matched, but the @code{&not} specification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 succeeds.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1233 @item &define
52840
590f500fb14b (Edebug Execution Modes): Clarify t.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1234 @c @kindex &define @r{(Edebug)}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 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
1236 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
1237 after the defining form), but forms inside it typically will be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 instrumented. The @code{&define} keyword should be the first element in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 a list specification.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 @item nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 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
1243 current argument list level; otherwise it fails. See sublist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 specifications and the backquote example below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 @item gate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 @cindex preventing backtracking
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 No argument is matched but backtracking through the gate is disabled
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 while matching the remainder of the specifications at this level. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 is primarily used to generate more specific syntax error messages. See
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251 @ref{Backtracking}, for more details. Also see the @code{let} example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 @item @var{other-symbol}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 @cindex indirect specifications
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 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
1257 indirect specification.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1258
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1259 If the symbol has an Edebug specification, this @dfn{indirect
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1260 specification} should be either a list specification that is used in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1261 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
1262 arguments. The specification may be defined with @code{def-edebug-spec}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 just as for macros. See the @code{defun} example below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 Otherwise, the symbol should be a predicate. The predicate is called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 with the argument and the specification fails if the predicate returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 @code{nil}. In either case, that argument is not instrumented.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 Some suitable predicates include @code{symbolp}, @code{integerp},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 @code{stringp}, @code{vectorp}, and @code{atom}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 @item [@var{elements}@dots{}]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273 @cindex [@dots{}] (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274 A vector of elements groups the elements into a single @dfn{group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275 specification}. Its meaning has nothing to do with vectors.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 @item "@var{string}"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 The argument should be a symbol named @var{string}. This specification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1279 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1280 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
1281
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1282 @item (vector @var{elements}@dots{})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1283 The argument should be a vector whose elements must match the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1284 @var{elements} in the specification. See the backquote example below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1285
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1286 @item (@var{elements}@dots{})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1287 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
1288 a list whose elements match the specification @var{elements}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290 @cindex dotted lists (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 A sublist specification may be a dotted list and the corresponding list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292 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
1293 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
1294 grouping or an indirect specification, e.g., @code{(spec . [(more
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295 specs@dots{})])}) whose elements match the non-dotted list arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1296 This is useful in recursive specifications such as in the backquote
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1297 example below. Also see the description of a @code{nil} specification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 above for terminating such recursion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1300 Note that a sublist specification written as @code{(specs . nil)}
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1301 is equivalent to @code{(specs)}, and @code{(specs .
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1302 (sublist-elements@dots{}))} is equivalent to @code{(specs
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1303 sublist-elements@dots{})}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1304 @end table
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 @c Need to document extensions with &symbol and :symbol
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1308 Here is a list of additional specifications that may appear only after
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 @code{&define}. See the @code{defun} example below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312 @item name
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1313 The argument, a symbol, is the name of the defining form.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315 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
1316 multiple name fields.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1317
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318 @item :name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319 This construct does not actually match an argument. The element
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 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
1321 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
1322 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
1323 than once.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325 @item arg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 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
1327 However, lambda-list keywords (symbols starting with @samp{&})
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1328 are not allowed.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330 @item lambda-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 @cindex lambda-list (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 This matches a lambda list---the argument list of a lambda expression.
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 def-body
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 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
1336 @code{body}, described above, but a definition body must be instrumented
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1337 with a different Edebug call that looks up information associated with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338 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
1339 within the definition.
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 def-form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 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
1343 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
1344 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
1345 tracing information is not output when the form is executed. See the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 @code{interactive} example below.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349 @node Backtracking
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1350 @subsubsection Backtracking in Specifications
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1351
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1352 @cindex backtracking
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 @cindex syntax error (Edebug)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 If a specification fails to match at some point, this does not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 necessarily mean a syntax error will be signaled; instead,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356 @dfn{backtracking} will take place until all alternatives have been
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357 exhausted. Eventually every element of the argument list must be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 matched by some element in the specification, and every required element
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359 in the specification must match some argument.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1360
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1361 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
1362 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
1363 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
1364 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
1365 that backtracking is also reenabled automatically in several situations;
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1366 it is reenabled when a new alternative is established by
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1367 @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
1368 processing a sublist, group, or indirect specification. The effect of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1369 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
1370 level currently being processed and lower levels.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1372 Backtracking is disabled while matching any of the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1373 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
1374 @code{def-body}). These specifications will match any form so any error
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 must be in the form itself rather than at a higher level.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1377 Backtracking is also disabled after successfully matching a quoted
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378 symbol or string specification, since this usually indicates a
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1379 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
1380 all begin with the same symbol, you can usually work around this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1381 constraint by factoring the symbol out of the alternatives, e.g.,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1382 @code{["foo" &or [first case] [second case] ...]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383
53595
7ea1b7196d49 *** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents: 53592
diff changeset
1384 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
1385 automatically disabled, but occasionally it is useful to explicitly
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1386 disable backtracking by using the @code{gate} specification. This is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1387 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
1388 example of the @code{let} specification.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1389
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390 @node Specification Examples
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1391 @subsubsection Specification Examples
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1392
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1393 It may be easier to understand Edebug specifications by studying
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1394 the examples provided here.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1395
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1396 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
1397 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
1398 optional expression. In the specification below, notice the @code{gate}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1399 inside of the sublist to prevent backtracking once a sublist is found.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1400
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402 (def-edebug-spec let
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1403 ((&rest
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404 &or symbolp (gate symbolp &optional form))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405 body))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 Edebug uses the following specifications for @code{defun} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 @code{defmacro} and the associated argument list and @code{interactive}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 specifications. It is necessary to handle interactive forms specially
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411 since an expression argument it is actually evaluated outside of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 function body.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1414 @smallexample
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1415 (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
1416 (def-edebug-spec defun
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1417 (&define name lambda-list
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1418 [&optional stringp] ; @r{Match the doc string, if present.}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 [&optional ("interactive" interactive)]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420 def-body))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422 (def-edebug-spec lambda-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423 (([&rest arg]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 [&optional ["&optional" arg &rest arg]]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1425 &optional ["&rest" arg]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426 )))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1427
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428 (def-edebug-spec interactive
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429 (&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
1430 @end smallexample
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432 The specification for backquote below illustrates how to match
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1433 dotted lists and use @code{nil} to terminate recursion. It also
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1434 illustrates how components of a vector may be matched. (The actual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1435 specification defined by Edebug does not support dotted lists because
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1436 doing so causes very deep recursion that could fail.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1437
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1438 @smallexample
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1439 (def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 (def-edebug-spec backquote-form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 (backquote-form . [&or nil backquote-form])
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 (vector &rest backquote-form)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 sexp))
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
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449 @node Edebug Options
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450 @subsection Edebug Options
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452 These options affect the behavior of Edebug:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @defopt edebug-setup-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 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
1456 value, Edebug will call those functions once and then
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 @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
1458 load up Edebug specifications associated with a package you are using
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 but only when you also use Edebug.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 @xref{Instrumenting}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 @defopt edebug-all-defs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464 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
1465 @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
1466 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
1467 and @code{eval-current-buffer}.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1468
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1469 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
1470 option. @xref{Instrumenting}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 @defopt edebug-all-forms
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1474 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
1475 @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
1476 instrument all forms, even those that don't define anything.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1477 This doesn't apply to loading or evaluations in the minibuffer.
6558
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 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
1480 option. @xref{Instrumenting}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483 @defopt edebug-save-windows
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484 If this is non-@code{nil}, Edebug saves and restores the window
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1485 configuration. That takes some time, so if your program does not care
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486 what happens to the window configurations, it is better to set this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 variable to @code{nil}.
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 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
1490 restored.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1491
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492 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
1493 interactively. @xref{Edebug Display Update}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496 @defopt edebug-save-displayed-buffer-points
7252
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1497 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
1498 displayed buffers.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1499
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 Saving and restoring point in other buffers is necessary if you are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1501 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
1502 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
1503 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
1504
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 Saving and restoring point in all buffers is expensive, since it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1506 requires selecting each window twice, so enable this only if you need
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507 it. @xref{Edebug Display Update}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1509
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 @defopt edebug-initial-mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511 If this variable is non-@code{nil}, it specifies the initial execution
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 mode for Edebug when it is first activated. Possible values are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1513 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1514 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1516 The default value is @code{step}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 @xref{Edebug Execution Modes}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520 @defopt edebug-trace
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521 Non-@code{nil} means display a trace of function entry and exit.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522 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
1523 function entry or exit per line, indented by the recursion level.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1525 The default value is @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1527 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1529
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1530 @defopt edebug-test-coverage
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532 @xref{Coverage Testing}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44674
diff changeset
1535 @defopt edebug-continue-kbd-macro
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536 If non-@code{nil}, continue defining or executing any keyboard macro
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 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
1538 debugged.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 @xref{Edebug Execution Modes}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 @defopt edebug-on-error
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543 Edebug binds @code{debug-on-error} to this value, if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544 @code{debug-on-error} was previously @code{nil}. @xref{Trapping
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 Errors}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1547
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548 @defopt edebug-on-quit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549 Edebug binds @code{debug-on-quit} to this value, if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550 @code{debug-on-quit} was previously @code{nil}. @xref{Trapping
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551 Errors}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554 If you change the values of @code{edebug-on-error} or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555 @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
1556 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
1557 @c Not necessarily a deeper command level.
2ddb8063f154 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1558 @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
1559
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1560 @defopt edebug-global-break-condition
51652
55fb0658914a Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
1561 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
1562 the result is non-@code{nil}, then break. Errors are ignored.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 @xref{Global Break Condition}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 @end defopt
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52142
diff changeset
1565
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52142
diff changeset
1566 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52142
diff changeset
1567 arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52142
diff changeset
1568 @end ignore