Mercurial > hg > xemacs-beta
annotate man/lispref/edebug-inc.texi @ 5640:e6b5c49f9e13
Add autoload cookie to custom-set-face-bold
| author | Vin Shelton <acs@xemacs.org> |
|---|---|
| date | Sun, 08 Jan 2012 22:29:06 -0500 |
| parents | 755ae5b97edb |
| children | d11efddf3617 |
| rev | line source |
|---|---|
| 428 | 1 @comment -*-texinfo-*- |
| 2 | |
| 3 @node Edebug, , Compilation Errors, Top | |
| 4 @section Edebug | |
| 5 @cindex Edebug mode | |
| 6 | |
| 7 @cindex Edebug | |
| 8 Edebug is a source-level debugger for XEmacs Lisp programs that | |
| 9 provides the following features: | |
| 10 | |
| 11 @itemize @bullet | |
| 12 @item | |
| 13 Step through evaluation, stopping before and after each expression. | |
| 14 | |
| 15 @item | |
| 16 Set conditional or unconditional breakpoints, install embedded | |
| 17 breakpoints, or a global break event. | |
| 18 | |
| 19 @item | |
| 20 Trace slow or fast stopping briefly at each stop point, or | |
| 21 each breakpoint. | |
| 22 | |
| 23 @item | |
| 24 Display expression results and evaluate expressions as if outside of | |
| 444 | 25 Edebug. Interface with the custom printing package |
| 428 | 26 for printing circular structures. |
| 27 | |
| 444 | 28 @item |
| 428 | 29 Automatically reevaluate a list of expressions and |
| 30 display their results each time Edebug updates the display. | |
| 31 | |
| 32 @item | |
| 33 Output trace info on function enter and exit. | |
| 34 | |
| 35 @item | |
| 36 Errors stop before the source causing the error. | |
| 37 | |
| 38 @item | |
| 39 Display backtrace without Edebug calls. | |
| 40 | |
| 41 @item | |
| 42 Allow specification of argument evaluation for macros and defining forms. | |
| 43 | |
| 44 @item | |
| 45 Provide rudimentary coverage testing and display of frequency counts. | |
| 46 | |
| 47 @end itemize | |
| 48 | |
| 49 The first three sections should tell you enough about Edebug to enable | |
| 50 you to use it. | |
| 51 | |
| 52 @menu | |
| 53 * Using Edebug:: Introduction to use of Edebug. | |
| 54 * Instrumenting:: You must first instrument code. | |
| 55 * Edebug Execution Modes:: Execution modes, stopping more or less often. | |
| 56 * Jumping:: Commands to jump to a specified place. | |
| 57 * Edebug Misc:: Miscellaneous commands. | |
| 58 * Breakpoints:: Setting breakpoints to make the program stop. | |
| 59 * Trapping Errors:: trapping errors with Edebug. | |
| 60 * Edebug Views:: Views inside and outside of Edebug. | |
| 61 * Edebug Eval:: Evaluating expressions within Edebug. | |
| 62 * Eval List:: Automatic expression evaluation. | |
| 63 * Reading in Edebug:: Customization of reading. | |
| 64 * Printing in Edebug:: Customization of printing. | |
| 65 * Tracing:: How to produce tracing output. | |
| 66 * Coverage Testing:: How to test evaluation coverage. | |
| 67 * The Outside Context:: Data that Edebug saves and restores. | |
| 68 * Instrumenting Macro Calls:: Specifying how to handle macro calls. | |
| 69 * Edebug Options:: Option variables for customizing Edebug. | |
| 70 @end menu | |
| 71 | |
| 72 @node Using Edebug | |
| 73 @subsection Using Edebug | |
| 74 | |
| 75 To debug an XEmacs Lisp program with Edebug, you must first | |
| 76 @dfn{instrument} the Lisp code that you want to debug. If you want to | |
| 77 just try it now, load @file{edebug.el}, move point into a definition and | |
| 78 do @kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). | |
| 79 See @ref{Instrumenting} for alternative ways to instrument code. | |
| 80 | |
| 81 Once a function is instrumented, any call to the function activates | |
| 82 Edebug. Activating Edebug may stop execution and let you step through | |
| 83 the function, or it may update the display and continue execution while | |
| 84 checking for debugging commands, depending on the selected Edebug | |
| 85 execution mode. The initial execution mode is @code{step}, by default, | |
| 86 which does stop execution. @xref{Edebug Execution Modes}. | |
| 87 | |
| 88 Within Edebug, you normally view an XEmacs buffer showing the source of | |
| 89 the Lisp function you are debugging. This is referred to as the | |
| 90 @dfn{source code buffer}---but note that it is not always the same | |
| 91 buffer depending on which function is currently being executed. | |
| 92 | |
| 93 An arrow at the left margin indicates the line where the function is | |
| 94 executing. Point initially shows where within the line the function is | |
| 95 executing, but you can move point yourself. | |
| 96 | |
| 97 If you instrument the definition of @code{fac} (shown below) and then | |
| 98 execute @code{(fac 3)}, here is what you normally see. Point is at the | |
| 99 open-parenthesis before @code{if}. | |
| 100 | |
| 101 @example | |
| 102 (defun fac (n) | |
| 103 =>@point{}(if (< 0 n) | |
| 104 (* n (fac (1- n))) | |
| 105 1)) | |
| 106 @end example | |
| 107 | |
| 108 @cindex stop points | |
| 109 The places within a function where Edebug can stop execution are called | |
| 110 @dfn{stop points}. These occur both before and after each subexpression | |
| 444 | 111 that is a list, and also after each variable reference. |
| 428 | 112 Here we show with periods the stop points found in the function |
| 113 @code{fac}: | |
| 114 | |
| 115 @example | |
| 116 (defun fac (n) | |
| 117 .(if .(< 0 n.). | |
| 118 .(* n. .(fac (1- n.).).). | |
| 119 1).) | |
| 120 @end example | |
| 121 | |
| 122 While the source code buffer is selected, the special commands of Edebug | |
| 123 are available in it, in addition to the commands of XEmacs Lisp mode. | |
| 124 (The buffer is temporarily made read-only, however.) For example, you | |
| 125 can type the Edebug command @key{SPC} to execute until the next stop | |
| 126 point. If you type @key{SPC} once after entry to @code{fac}, here is | |
| 127 the display you will see: | |
| 128 | |
| 129 @example | |
| 130 (defun fac (n) | |
| 131 =>(if @point{}(< 0 n) | |
| 132 (* n (fac (1- n))) | |
| 133 1)) | |
| 134 @end example | |
| 135 | |
| 136 When Edebug stops execution after an expression, it displays the | |
| 444 | 137 expression's value in the echo area. |
| 428 | 138 |
| 139 Other frequently used commands are @kbd{b} to set a breakpoint at a stop | |
| 140 point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to | |
| 141 exit to the top-level command loop. Type @kbd{?} to display a list of | |
| 142 all Edebug commands. | |
| 143 | |
| 144 | |
| 145 @node Instrumenting | |
| 146 @subsection Instrumenting for Edebug | |
| 147 | |
| 148 In order to use Edebug to debug Lisp code, you must first | |
| 149 @dfn{instrument} the code. Instrumenting a form inserts additional code | |
| 150 into it which invokes Edebug at the proper places. Furthermore, if | |
| 151 Edebug detects a syntax error while instrumenting, point is left at the | |
| 152 erroneous code and an @code{invalid-read-syntax} error is signaled. | |
| 153 | |
| 154 @kindex C-M-x | |
| 155 @findex eval-defun (Edebug) | |
| 156 @findex edebug-all-defs | |
| 157 Once you have loaded Edebug, the command @kbd{C-M-x} | |
| 158 (@code{eval-defun}) is redefined so that when invoked with a prefix | |
| 159 argument on a definition, it instruments the definition before | |
| 160 evaluating it. (The source code itself is not modified.) If the | |
| 161 variable @code{edebug-all-defs} is non-@code{nil}, that inverts the | |
| 162 meaning of the prefix argument: then @kbd{C-M-x} instruments the | |
| 163 definition @emph{unless} it has a prefix argument. The default value of | |
| 164 @code{edebug-all-defs} is @code{nil}. The command @kbd{M-x | |
| 165 edebug-all-defs} toggles the value of the variable | |
| 166 @code{edebug-all-defs}. | |
| 167 | |
| 168 @findex edebug-all-forms | |
| 169 @findex eval-region (Edebug) | |
| 170 @findex eval-current-buffer (Edebug) | |
| 171 If @code{edebug-all-defs} is non-@code{nil}, then the commands | |
| 172 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} | |
| 173 also instrument any definitions they evaluate. Similarly, | |
| 174 @code{edebug-all-forms} controls whether @code{eval-region} should | |
| 175 instrument @emph{any} form, even non-defining forms. This doesn't apply | |
| 176 to loading or evaluations in the minibuffer. The command @kbd{M-x | |
| 177 edebug-all-forms} toggles this option. | |
| 178 | |
| 179 @findex edebug-eval-top-level-form | |
| 180 Another command, @kbd{M-x edebug-eval-top-level-form}, is available to | |
| 181 instrument any top-level form regardless of the value of | |
| 182 @code{edebug-all-defs} or @code{edebug-all-forms}. | |
| 183 | |
| 184 Just before Edebug instruments any code, it calls any functions in the | |
| 185 variable @code{edebug-setup-hook} and resets its value to @code{nil}. | |
| 186 You could use this to load up Edebug specifications associated with a | |
| 187 package you are using but only when you also use Edebug. For example, | |
| 188 @file{my-specs.el} may be loaded automatically when you use | |
| 189 @code{my-package} with Edebug by including the following code in | |
| 190 @file{my-package.el}. | |
| 191 | |
| 192 @example | |
| 444 | 193 (add-hook 'edebug-setup-hook |
| 428 | 194 (function (lambda () (require 'my-specs)))) |
| 195 @end example | |
| 196 | |
| 197 While Edebug is active, the command @kbd{I} | |
| 198 (@code{edebug-instrument-callee}) instruments the definition of the | |
| 199 function or macro called by the list form after point, if is not already | |
| 200 instrumented. If the location of the definition is not known to Edebug, | |
| 201 this command cannot be used. After loading Edebug, @code{eval-region} | |
| 202 records the position of every definition it evaluates, even if not | |
| 203 instrumenting it. Also see the command @kbd{i} (@ref{Jumping}) which | |
| 204 steps into the callee. | |
| 205 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
206 @cindex special operators (Edebug) |
| 428 | 207 @cindex interactive commands (Edebug) |
| 208 @cindex anonymous lambda expressions (Edebug) | |
| 209 @cindex Common Lisp (Edebug) | |
| 210 @pindex cl.el (Edebug) | |
| 211 @pindex cl-specs.el | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
212 Edebug knows how to instrument all the standard special operators, an |
| 428 | 213 interactive form with an expression argument, anonymous lambda |
| 214 expressions, and other defining forms. (Specifications for macros | |
| 215 defined by @file{cl.el} (version 2.03) are provided in | |
| 216 @file{cl-specs.el}.) Edebug cannot know what a user-defined macro will | |
| 217 do with the arguments of a macro call so you must tell it. See | |
| 218 @ref{Instrumenting Macro Calls} for the details. | |
| 219 | |
| 220 @findex eval-expression (Edebug) | |
| 221 Note that a couple ways remain to evaluate expressions without | |
| 222 instrumenting them. Loading a file via the @code{load} subroutine does | |
| 223 not instrument expressions for Edebug. Evaluations in the minibuffer | |
| 224 via @code{eval-expression} (@kbd{M-ESC}) are not instrumented. | |
| 225 | |
| 226 To remove instrumentation from a definition, simply reevaluate it with | |
| 227 one of the non-instrumenting commands, or reload the file. | |
| 228 | |
| 229 See @ref{Edebug Eval} for other evaluation functions available | |
| 230 inside of Edebug. | |
| 231 | |
| 232 | |
| 233 @node Edebug Execution Modes | |
| 234 @subsection Edebug Execution Modes | |
| 235 | |
| 236 @cindex Edebug execution modes | |
| 237 Edebug supports several execution modes for running the program you are | |
| 238 debugging. We call these alternatives @dfn{Edebug execution modes}; do | |
| 239 not confuse them with major or minor modes. The current Edebug | |
| 240 execution mode determines how Edebug displays the progress of the | |
| 241 evaluation, whether it stops at each stop point, or continues to the | |
| 242 next breakpoint, for example. | |
| 243 | |
| 244 Normally, you specify the Edebug execution mode by typing a command | |
| 245 to continue the program in a certain mode. Here is a table of these | |
| 246 commands. All except for @kbd{S} resume execution of the program, at | |
| 247 least for a certain distance. | |
| 248 | |
| 249 @table @kbd | |
| 250 @item S | |
| 251 Stop: don't execute any more of the program for now, just wait for more | |
| 252 Edebug commands (@code{edebug-stop}). | |
| 253 | |
| 254 @item @key{SPC} | |
| 255 Step: stop at the next stop point encountered (@code{edebug-step-mode}). | |
| 256 | |
| 257 @item n | |
| 258 Next: stop at the next stop point encountered after an expression | |
| 259 (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in | |
| 260 @ref{Edebug Misc}. | |
| 261 | |
| 262 @item t | |
| 263 Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}). | |
| 264 | |
| 265 @item T | |
| 266 Rapid trace: update at each stop point, but don't actually | |
| 267 pause (@code{edebug-Trace-fast-mode}). | |
| 268 | |
| 269 @item g | |
| 270 Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}. | |
| 271 | |
| 272 @item c | |
| 273 Continue: pause for one second at each breakpoint, but don't stop | |
| 274 (@code{edebug-continue-mode}). | |
| 275 | |
| 276 @item C | |
| 277 Rapid continue: update at each breakpoint, but don't actually pause | |
| 278 (@code{edebug-Continue-fast-mode}). | |
| 279 | |
| 280 @item G | |
| 281 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You | |
| 282 can still stop the program by hitting any key. | |
| 283 @end table | |
| 284 | |
| 285 In general, the execution modes earlier in the above list run the | |
| 286 program more slowly or stop sooner. | |
| 287 | |
| 288 When you enter a new Edebug level, the initial execution mode comes from | |
| 289 the value of the variable @code{edebug-initial-mode}. By default, this | |
| 290 specifies @code{step} mode. Note that you may reenter the same Edebug | |
| 444 | 291 level several times if, for example, an instrumented function is called |
| 428 | 292 several times from one command. |
| 293 | |
| 294 While executing or tracing, you can interrupt the execution by typing | |
| 295 any Edebug command. Edebug stops the program at the next stop point and | |
| 296 then executes the command that you typed. For example, typing @kbd{t} | |
| 297 during execution switches to trace mode at the next stop point. You can | |
| 298 use @kbd{S} to stop execution without doing anything else. | |
| 299 | |
| 300 If your function happens to read input, a character you hit intending to | |
| 301 interrupt execution may be read by the function instead. You can avoid | |
| 302 such unintended results by paying attention to when your program wants | |
| 303 input. | |
| 304 | |
| 305 @cindex keyboard macros (Edebug) | |
| 306 Keyboard macros containing Edebug commands do not work; when you exit | |
| 307 from Edebug, to resume the program, whether you are defining or | |
| 308 executing a keyboard macro is forgotten. Also, defining or executing a | |
| 309 keyboard macro outside of Edebug does not affect the command loop inside | |
| 310 Edebug. This is usually an advantage. But see | |
| 311 @code{edebug-continue-kbd-macro}. | |
| 312 | |
| 313 | |
| 314 @node Jumping | |
| 315 @subsection Jumping | |
| 316 | |
| 317 Commands described here let you jump to a specified location. | |
| 318 All, except @kbd{i}, use temporary breakpoints to establish the stop | |
| 319 point and then switch to @code{go} mode. Any other breakpoint reached | |
| 320 before the intended stop point will also stop execution. See | |
| 321 @ref{Breakpoints} for the details on breakpoints. | |
| 322 | |
| 323 @table @kbd | |
| 324 @item f | |
| 325 Run the program forward over one expression | |
| 326 (@code{edebug-forward-sexp}). More precisely, set a temporary | |
| 327 breakpoint at the position that @kbd{C-M-f} would reach, then execute in | |
| 328 @code{go} mode so that the program will stop at breakpoints. | |
| 329 | |
| 330 With a prefix argument @var{n}, the temporary breakpoint is placed | |
| 331 @var{n} sexps beyond point. If the containing list ends before @var{n} | |
| 332 more elements, then the place to stop is after the containing | |
| 333 expression. | |
| 334 | |
| 335 Be careful that the position @kbd{C-M-f} finds is a place that the | |
| 336 program will really get to; this may not be true in a | |
| 337 @code{cond}, for example. | |
| 338 | |
| 339 This command does @code{forward-sexp} starting at point rather than the | |
| 340 stop point. If you want to execute one expression from the current stop | |
| 341 point, type @kbd{w} first, to move point there. | |
| 342 | |
| 343 @item o | |
| 344 Continue ``out of'' an expression (@code{edebug-step-out}). It places a | |
| 444 | 345 temporary breakpoint at the end of the sexp containing point. |
| 428 | 346 |
| 347 If the containing sexp is a function definition itself, it continues | |
| 348 until just before the last sexp in the definition. If that is where you | |
| 349 are now, it returns from the function and then stops. In other words, | |
| 350 this command does not exit the currently executing function unless you | |
| 351 are positioned after the last sexp. | |
| 352 | |
| 353 @item I | |
| 354 Step into the function or macro after point after first ensuring that it | |
| 355 is instrumented. It does this by calling @code{edebug-on-entry} and | |
| 356 then switching to @code{go} mode. | |
| 357 | |
| 358 Although the automatic instrumentation is convenient, it is not | |
| 359 later automatically uninstrumented. | |
| 360 | |
| 361 @item h | |
| 362 Proceed to the stop point near where point is using a temporary | |
| 363 breakpoint (@code{edebug-goto-here}). | |
| 364 | |
| 365 @end table | |
| 366 | |
| 367 All the commands in this section may fail to work as expected in case | |
| 368 of nonlocal exit, because a nonlocal exit can bypass the temporary | |
| 369 breakpoint where you expected the program to stop. | |
| 370 | |
| 371 @node Edebug Misc | |
| 372 @subsection Miscellaneous | |
| 373 | |
| 374 Some miscellaneous commands are described here. | |
| 375 | |
| 376 @table @kbd | |
| 377 @item ? | |
| 378 Display the help message for Edebug (@code{edebug-help}). | |
| 379 | |
| 380 @item C-] | |
| 381 Abort one level back to the previous command level | |
| 382 (@code{abort-recursive-edit}). | |
| 383 | |
| 384 @item q | |
| 385 Return to the top level editor command loop (@code{top-level}). This | |
| 386 exits all recursive editing levels, including all levels of Edebug | |
| 387 activity. However, instrumented code protected with | |
| 388 @code{unwind-protect} or @code{condition-case} forms may resume | |
| 389 debugging. | |
| 390 | |
| 391 @item Q | |
| 392 Like @kbd{q} but don't stop even for protected code | |
| 393 (@code{top-level-nonstop}). | |
| 394 | |
| 395 @item r | |
| 396 Redisplay the most recently known expression result in the echo area | |
| 397 (@code{edebug-previous-result}). | |
| 398 | |
| 399 @item d | |
| 400 Display a backtrace, excluding Edebug's own functions for clarity | |
| 401 (@code{edebug-backtrace}). | |
| 402 | |
| 403 You cannot use debugger commands in the backtrace buffer in Edebug as | |
| 404 you would in the standard debugger. | |
| 405 | |
| 406 The backtrace buffer is killed automatically when you continue | |
| 407 execution. | |
| 408 @end table | |
| 409 | |
| 410 From the Edebug recursive edit, you may invoke commands that activate | |
| 411 Edebug again recursively. Any time Edebug is active, you can quit to | |
| 412 the top level with @kbd{q} or abort one recursive edit level with | |
| 444 | 413 @kbd{C-]}. You can display a backtrace of all the |
| 428 | 414 pending evaluations with @kbd{d}. |
| 415 | |
| 416 | |
| 417 @node Breakpoints | |
| 418 @subsection Breakpoints | |
| 419 | |
| 420 @cindex breakpoints | |
| 421 There are three more ways to stop execution once it has started: | |
| 422 breakpoints, the global break condition, and embedded breakpoints. | |
| 423 | |
| 424 While using Edebug, you can specify @dfn{breakpoints} in the program you | |
| 425 are testing: points where execution should stop. You can set a | |
| 426 breakpoint at any stop point, as defined in @ref{Using Edebug}. For | |
| 427 setting and unsetting breakpoints, the stop point that is affected is | |
| 428 the first one at or after point in the source code buffer. Here are the | |
| 429 Edebug commands for breakpoints: | |
| 430 | |
| 431 @table @kbd | |
| 432 @item b | |
| 433 Set a breakpoint at the stop point at or after point | |
| 434 (@code{edebug-set-breakpoint}). If you use a prefix argument, the | |
| 435 breakpoint is temporary (it turns off the first time it stops the | |
| 436 program). | |
| 437 | |
| 438 @item u | |
| 439 Unset the breakpoint (if any) at the stop point at or after the current | |
| 440 point (@code{edebug-unset-breakpoint}). | |
| 441 | |
| 442 @item x @var{condition} @key{RET} | |
| 443 Set a conditional breakpoint which stops the program only if | |
| 444 @var{condition} evaluates to a non-@code{nil} value | |
| 445 (@code{edebug-set-conditional-breakpoint}). If you use a prefix | |
| 446 argument, the breakpoint is temporary (it turns off the first time it | |
| 447 stops the program). | |
| 448 | |
| 449 @item B | |
| 450 Move point to the next breakpoint in the definition | |
| 451 (@code{edebug-next-breakpoint}). | |
| 452 @end table | |
| 453 | |
| 454 While in Edebug, you can set a breakpoint with @kbd{b} and unset one | |
| 455 with @kbd{u}. First you must move point to a position at or before the | |
| 456 desired Edebug stop point, then hit the key to change the breakpoint. | |
| 457 Unsetting a breakpoint that has not been set does nothing. | |
| 458 | |
| 459 Reevaluating or reinstrumenting a definition clears all its breakpoints. | |
| 460 | |
| 461 A @dfn{conditional breakpoint} tests a condition each time the program | |
| 462 gets there. To set a conditional breakpoint, use @kbd{x}, and specify | |
| 463 the condition expression in the minibuffer. Setting a conditional | |
| 464 breakpoint at a stop point that already has a conditional breakpoint | |
| 465 puts the current condition expression in the minibuffer so you can edit | |
| 466 it. | |
| 467 | |
| 468 You can make both conditional and unconditional breakpoints | |
| 469 @dfn{temporary} by using a prefix arg to the command to set the | |
| 470 breakpoint. After breaking at a temporary breakpoint, it is | |
| 471 automatically cleared. | |
| 472 | |
| 473 Edebug always stops or pauses at a breakpoint except when the Edebug | |
| 474 mode is @code{Go-nonstop}. In that mode, it ignores breakpoints entirely. | |
| 475 | |
| 476 To find out where your breakpoints are, use @kbd{B}, which | |
| 477 moves point to the next breakpoint in the definition following point, or | |
| 478 to the first breakpoint if there are no following breakpoints. This | |
| 479 command does not continue execution---it just moves point in the buffer. | |
| 480 | |
| 481 @menu | |
| 444 | 482 * Global Break Condition:: Breaking on an event. |
| 428 | 483 * Embedded Breakpoints:: Embedding breakpoints in code. |
| 484 @end menu | |
| 485 | |
| 486 | |
| 487 @node Global Break Condition | |
| 488 @subsubsection Global Break Condition | |
| 489 | |
| 490 @cindex stopping on events | |
| 491 @cindex global break condition | |
| 492 In contrast to breaking when execution reaches specified locations, | |
| 493 you can also cause a break when a certain event occurs. The @dfn{global | |
| 494 break condition} is a condition that is repeatedly evaluated at every | |
| 495 stop point. If it evaluates to a non-@code{nil} value, then execution | |
| 496 is stopped or paused depending on the execution mode, just like a | |
| 497 breakpoint. Any errors that might occur as a result of evaluating the | |
| 444 | 498 condition are ignored, as if the result were @code{nil}. |
| 428 | 499 |
| 500 @findex edebug-set-global-break-condition | |
| 501 @vindex edebug-global-break-condition | |
| 502 You can set or edit the condition expression, stored in | |
| 503 @code{edebug-global-break-condition}, using @kbd{X} | |
| 504 (@code{edebug-set-global-break-condition}). | |
| 505 | |
| 506 Using the global break condition is perhaps the fastest way | |
| 507 to find where in your code some event occurs, but since it is rather | |
| 508 expensive you should reset the condition to @code{nil} when not in use. | |
| 509 | |
| 510 | |
| 511 @node Embedded Breakpoints | |
| 512 @subsubsection Embedded Breakpoints | |
| 513 | |
| 514 @findex edebug | |
| 515 @cindex embedded breakpoints | |
| 516 Since all breakpoints in a definition are cleared each time you | |
| 517 reinstrument it, you might rather create an @dfn{embedded breakpoint} | |
| 518 which is simply a call to the function @code{edebug}. You can, of | |
| 519 course, make such a call conditional. For example, in the @code{fac} | |
| 520 function, insert the first line as shown below to stop when the argument | |
| 521 reaches zero: | |
| 522 | |
| 523 @example | |
| 524 (defun fac (n) | |
| 525 (if (= n 0) (edebug)) | |
| 526 (if (< 0 n) | |
| 527 (* n (fac (1- n))) | |
| 528 1)) | |
| 529 @end example | |
| 530 | |
| 531 When the @code{fac} definition is instrumented and the function is | |
| 532 called, Edebug will stop before the call to @code{edebug}. Depending on | |
| 533 the execution mode, Edebug will stop or pause. | |
| 534 | |
| 535 However, if no instrumented code is being executed, calling | |
| 536 @code{edebug} will instead invoke @code{debug}. Calling @code{debug} | |
| 537 will always invoke the standard backtrace debugger. | |
| 538 | |
| 539 | |
| 540 @node Trapping Errors | |
| 541 @subsection Trapping Errors | |
| 542 | |
| 543 @vindex edebug-on-error | |
| 544 @vindex edebug-on-quit | |
| 545 An error may be signaled by subroutines or XEmacs Lisp code. If a signal | |
| 546 is not handled by a @code{condition-case}, this indicates an | |
| 547 unrecognized situation has occurred. If Edebug is not active when an | |
| 548 unhandled error is signaled, @code{debug} is run normally (if | |
| 549 @code{debug-on-error} is non-@code{nil}). But while Edebug is active, | |
| 550 @code{debug-on-error} and @code{debug-on-quit} are bound to | |
| 551 @code{edebug-on-error} and @code{edebug-on-quit}, which are both | |
| 552 @code{t} by default. Actually, if @code{debug-on-error} already has | |
| 553 a non-@code{nil} value, that value is still used. | |
| 554 | |
| 555 It is best to change the values of @code{edebug-on-error} or | |
| 556 @code{edebug-on-quit} when Edebug is not active since their values won't | |
| 557 be used until the next time Edebug is invoked at a deeper command level. | |
| 558 If you only change @code{debug-on-error} or @code{debug-on-quit} while | |
| 559 Edebug is active, these changes will be forgotten when Edebug becomes | |
| 560 inactive. Furthermore, during Edebug's recursive edit, these variables | |
| 561 are bound to the values they had outside of Edebug. | |
| 562 | |
| 563 Edebug shows you the last stop point that it knew about before the | |
| 564 error was signaled. This may be the location of a call to a function | |
| 565 which was not instrumented, within which the error actually occurred. | |
| 566 For an unbound variable error, the last known stop point might be quite | |
| 567 distant from the offending variable. If the cause of the error is not | |
| 568 obvious at first, note that you can also get a full backtrace inside of | |
| 569 Edebug (see @ref{Edebug Misc}). | |
| 570 | |
| 571 Edebug can also trap signals even if they are handled. If | |
| 572 @code{debug-on-error} is a list of signal names, Edebug will stop when | |
| 573 any of these errors are signaled. Edebug shows you the last known stop | |
| 574 point just as for unhandled errors. After you continue execution, the | |
| 575 error is signaled again (but without being caught by Edebug). Edebug | |
| 576 can only trap errors that are handled if they are signaled in Lisp code | |
| 577 (not subroutines) since it does so by temporarily replacing the | |
| 578 @code{signal} function. | |
| 579 | |
| 580 | |
| 581 @node Edebug Views | |
| 582 @subsection Edebug Views | |
| 583 | |
| 584 The following Edebug commands let you view aspects of the buffer and | |
| 585 window status that obtained before entry to Edebug. | |
| 586 | |
| 587 @table @kbd | |
| 588 @item v | |
| 589 View the outside window configuration (@code{edebug-view-outside}). | |
| 590 | |
| 591 @item p | |
| 592 Temporarily display the outside current buffer with point at its outside | |
| 593 position (@code{edebug-bounce-point}). If prefix arg is supplied, sit for | |
| 594 that many seconds instead. | |
| 595 | |
| 596 @item w | |
| 597 Move point back to the current stop point (@code{edebug-where}) in the | |
| 598 source code buffer. Also, if you use this command in another window | |
| 599 displaying the same buffer, this window will be used instead to | |
| 600 display the buffer in the future. | |
| 601 | |
| 602 @item W | |
| 603 Toggle the @code{edebug-save-windows} variable which indicates whether | |
| 604 the outside window configuration is saved and restored | |
| 605 (@code{edebug-toggle-save-windows}). Also, each time it is toggled on, | |
| 606 make the outside window configuration the same as the current window | |
| 607 configuration. | |
| 608 | |
| 609 With a prefix argument, @code{edebug-toggle-save-windows} only toggles | |
| 610 saving and restoring of the selected window. To specify a window that | |
| 611 is not displaying the source code buffer, you must use @kbd{C-xXW} from | |
| 612 the global keymap. | |
| 613 | |
| 614 | |
| 615 @end table | |
| 616 | |
| 617 You can view the outside window configuration with @kbd{v} or just | |
| 618 bounce to the current point in the current buffer with @kbd{p}, even if | |
| 619 it is not normally displayed. After moving point, you may wish to pop | |
| 620 back to the stop point with @kbd{w} from a source code buffer. | |
| 621 | |
| 622 By using @kbd{W} twice, Edebug again saves and restores the | |
| 623 outside window configuration, but to the current configuration. This is | |
| 624 a convenient way to, for example, add another buffer to be displayed | |
| 625 whenever Edebug is active. However, the automatic redisplay of | |
| 626 @samp{*edebug*} and @samp{*edebug-trace*} may conflict with the buffers | |
| 627 you wish to see unless you have enough windows open. | |
| 628 | |
| 629 | |
| 630 @node Edebug Eval | |
| 631 @subsection Evaluation | |
| 632 | |
| 633 While within Edebug, you can evaluate expressions ``as if'' Edebug were | |
| 634 not running. Edebug tries to be invisible to the expression's | |
| 635 evaluation and printing. Evaluation of expressions that cause side | |
| 636 effects will work as expected except for things that Edebug explicitly | |
| 637 saves and restores. See @ref{The Outside Context} for details on this | |
| 638 process. Also see @ref{Reading in Edebug} and @ref{Printing in Edebug} | |
| 639 for topics related to evaluation. | |
| 640 | |
| 641 @table @kbd | |
| 642 @item e @var{exp} @key{RET} | |
| 643 Evaluate expression @var{exp} in the context outside of Edebug | |
| 644 (@code{edebug-eval-expression}). In other words, Edebug tries to avoid | |
| 645 altering the effect of @var{exp}. | |
| 646 | |
| 647 @item M-@key{ESC} @var{exp} @key{RET} | |
| 648 Evaluate expression @var{exp} in the context of Edebug itself. | |
| 649 | |
| 650 @item C-x C-e | |
| 651 Evaluate the expression before point, in the context outside of Edebug | |
| 652 (@code{edebug-eval-last-sexp}). | |
| 653 @end table | |
| 654 | |
| 655 @cindex lexical binding (Edebug) | |
| 656 Edebug supports evaluation of expressions containing references to | |
| 657 lexically bound symbols created by the following constructs in | |
| 658 @file{cl.el} (version 2.03 or later): @code{lexical-let}, | |
| 659 @code{macrolet}, and @code{symbol-macrolet}. | |
| 660 | |
| 661 | |
| 662 @node Eval List | |
| 663 @subsection Evaluation List Buffer | |
| 664 | |
| 665 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to | |
| 666 evaluate expressions interactively. You can also set up the | |
| 667 @dfn{evaluation list} of expressions to be evaluated automatically each | |
| 668 time Edebug updates the display. | |
| 669 | |
| 670 @table @kbd | |
| 671 @item E | |
| 672 Switch to the evaluation list buffer @samp{*edebug*} | |
| 673 (@code{edebug-visit-eval-list}). | |
| 674 @end table | |
| 675 | |
| 676 In the @samp{*edebug*} buffer you can use the commands of Lisp | |
| 677 Interaction as well as these special commands: | |
| 678 | |
| 679 @table @kbd | |
| 680 @item LFD | |
| 681 Evaluate the expression before point, in the outside context, and insert | |
| 682 the value in the buffer (@code{edebug-eval-print-last-sexp}). | |
| 683 | |
| 684 @item C-x C-e | |
| 685 Evaluate the expression before point, in the context outside of Edebug | |
| 686 (@code{edebug-eval-last-sexp}). | |
| 687 | |
| 688 @item C-c C-u | |
| 689 Build a new evaluation list from the first expression of each group, | |
| 690 reevaluate and redisplay (@code{edebug-update-eval-list}). Groups are | |
| 691 separated by comment lines. | |
| 692 | |
| 693 @item C-c C-d | |
| 694 Delete the evaluation list group that point is in | |
| 695 (@code{edebug-delete-eval-item}). | |
| 696 | |
| 697 @item C-c C-w | |
| 698 Switch back to the source code buffer at the current stop point | |
| 699 (@code{edebug-where}). | |
| 700 @end table | |
| 701 | |
| 702 You can evaluate expressions in the evaluation list window with | |
| 703 @kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*}; | |
| 704 but they are evaluated in the context outside of Edebug. | |
| 705 | |
| 706 @cindex evaluation list (Edebug) | |
| 707 The expressions you enter interactively (and their results) are lost | |
| 708 when you continue execution unless you add them to the | |
| 709 evaluation list with @kbd{C-c C-u}. This command builds a new list from | |
| 710 the first expression of each @dfn{evaluation list group}. Groups are | |
| 711 separated by comment lines. Be careful not to add expressions that | |
| 712 execute instrumented code otherwise an infinite loop will result. | |
| 713 | |
| 714 When the evaluation list is redisplayed, each expression is displayed | |
| 715 followed by the result of evaluating it, and a comment line. If an | |
| 716 error occurs during an evaluation, the error message is displayed in a | |
| 717 string as if it were the result. Therefore expressions that, for | |
| 718 example, use variables not currently valid do not interrupt your | |
| 719 debugging. | |
| 720 | |
| 721 Here is an example of what the evaluation list window looks like after | |
| 722 several expressions have been added to it: | |
| 723 | |
| 724 @smallexample | |
| 725 (current-buffer) | |
| 726 #<buffer *scratch*> | |
| 727 ;--------------------------------------------------------------- | |
| 728 (selected-window) | |
| 729 #<window 16 on *scratch*> | |
| 730 ;--------------------------------------------------------------- | |
| 731 (point) | |
| 732 196 | |
| 733 ;--------------------------------------------------------------- | |
| 734 bad-var | |
| 735 "Symbol's value as variable is void: bad-var" | |
| 736 ;--------------------------------------------------------------- | |
| 737 (recursion-depth) | |
| 738 0 | |
| 739 ;--------------------------------------------------------------- | |
| 740 this-command | |
| 741 eval-last-sexp | |
| 742 ;--------------------------------------------------------------- | |
| 743 @end smallexample | |
| 744 | |
| 745 To delete a group, move point into it and type @kbd{C-c C-d}, or simply | |
| 746 delete the text for the group and update the evaluation list with | |
| 747 @kbd{C-c C-u}. When you add a new group, be sure it is separated from | |
| 748 its neighbors by a comment line. | |
| 749 | |
| 750 After selecting @samp{*edebug*}, you can return to the source code | |
| 751 buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when | |
| 752 you continue execution, and recreated next time it is needed. | |
| 753 | |
| 754 | |
| 755 @node Reading in Edebug | |
| 756 @subsection Reading in Edebug | |
| 757 | |
| 758 @cindex reading (Edebug) | |
| 759 To instrument a form, Edebug first reads the whole form. Edebug | |
| 760 replaces the standard Lisp Reader with its own reader that remembers the | |
| 761 positions of expressions. This reader is used by the Edebug | |
| 762 replacements for @code{eval-region}, @code{eval-defun}, | |
| 763 @code{eval-buffer}, and @code{eval-current-buffer}. | |
| 764 | |
| 765 @pindex cl-read | |
| 766 Another package, @file{cl-read.el}, replaces the standard reader with | |
| 767 one that understands Common Lisp reader macros. If you use that | |
| 768 package, Edebug will automatically load @file{edebug-cl-read.el} to | |
| 769 provide corresponding reader macros that remember positions of | |
| 770 expressions. If you define new reader macros, you will have to define | |
| 771 similar reader macros for Edebug. | |
| 772 | |
| 773 | |
| 774 @node Printing in Edebug | |
| 775 @subsection Printing in Edebug | |
| 776 | |
| 777 @cindex printing (Edebug) | |
| 778 @cindex printing circular structures | |
| 779 @pindex cust-print | |
| 780 If the result of an expression in your program contains a circular | |
| 781 reference, you may get an error when Edebug attempts to print it. You | |
| 782 can set @code{print-length} to a non-zero value to limit the print | |
| 783 length of lists (the number of cdrs), and in Emacs 19, set | |
| 784 @code{print-level} to a non-zero value to limit the print depth of | |
| 785 lists. But you can print such circular structures and structures that | |
| 786 share elements more informatively by using the @file{cust-print} | |
| 787 package. | |
| 788 | |
| 789 To load @file{cust-print} and activate custom printing only for Edebug, | |
| 790 simply use the command @kbd{M-x edebug-install-custom-print}. To | |
| 791 restore the standard print functions, use @kbd{M-x | |
| 792 edebug-uninstall-custom-print}. You can also activate custom printing | |
| 793 for printing in any Lisp code; see the package for details. | |
| 794 | |
| 795 Here is an example of code that creates a circular structure: | |
| 796 | |
| 797 @example | |
| 798 (progn | |
| 799 (edebug-install-custom-print) | |
| 800 (setq a '(x y)) | |
| 801 (setcar a a)) | |
| 802 @end example | |
| 803 | |
| 804 Edebug will print the result of the @code{setcar} as @samp{Result: | |
| 805 #1=(#1# y)}. The @samp{#1=} notation names the structure that follows | |
| 806 it, and the @samp{#1#} notation references the previously named | |
| 807 structure. This notation is used for any shared elements of lists or | |
| 808 vectors. | |
| 809 | |
| 810 @vindex edebug-print-length | |
| 811 @vindex edebug-print-level | |
| 812 @vindex edebug-print-circle | |
| 813 @vindex print-readably | |
| 814 Independent of whether @file{cust-print} is active, while printing | |
| 815 results Edebug binds @code{print-length}, @code{print-level}, and | |
| 816 @code{print-circle} to @code{edebug-print-length} (@code{50}), | |
| 817 @code{edebug-print-level} (@code{50}), and @code{edebug-print-circle} | |
| 818 (@code{t}) respectively, if these values are non-@code{nil}. Also, | |
| 819 @code{print-readably} is bound to @code{nil} since some objects simply | |
| 820 cannot be printed readably. | |
| 821 | |
| 822 | |
| 823 @node Tracing | |
| 824 @subsection Tracing | |
| 825 | |
| 826 @cindex tracing | |
| 827 In addition to automatic stepping through source code, which is also | |
| 828 called @emph{tracing} (see @ref{Edebug Execution Modes}), Edebug can | |
| 829 produce a traditional trace listing of execution in a separate buffer, | |
| 830 @samp{*edebug-trace*}. | |
| 831 | |
| 832 @findex edebug-print-trace-before | |
| 833 @findex edebug-print-trace-after | |
| 444 | 834 If the variable @code{edebug-trace} is non-@code{nil}, each function entry and |
| 428 | 835 exit adds lines to the trace buffer. On function entry, Edebug prints |
| 836 @samp{::::@{} followed by the function name and argument values. On | |
| 837 function exit, Edebug prints @samp{::::@}} followed by the function name | |
| 838 and result of the function. The number of @samp{:}s is computed from | |
| 839 the recursion depth. The balanced braces in the trace buffer can be | |
| 840 used to find the matching beginning or end of function calls. These | |
| 841 displays may be customized by replacing the functions | |
| 842 @code{edebug-print-trace-before} and @code{edebug-print-trace-after}, | |
| 843 which take an arbitrary message string to print. | |
| 844 | |
| 845 @findex edebug-tracing | |
| 846 The macro @code{edebug-tracing} provides tracing similar to function | |
| 847 enter and exit tracing, but for arbitrary expressions. This macro | |
| 848 should be explicitly inserted by you around expressions you wish to | |
| 849 trace the execution of. The first argument is a message string | |
| 850 (evaluated), and the rest are expressions to evaluate. The result of | |
| 851 the last expression is returned. | |
| 852 | |
| 853 @findex edebug-trace | |
| 854 Finally, you can insert arbitrary strings into the trace buffer with | |
| 855 explicit calls to @code{edebug-trace}. The arguments of this function | |
| 856 are the same as for @code{message}, but a newline is always inserted | |
| 857 after each string printed in this way. | |
| 858 | |
| 859 @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace | |
| 860 buffer even if Edebug is not active. Every time the trace buffer is | |
| 861 added to, the window is scrolled to show the last lines inserted. | |
| 862 (There may be some display problems if you use tracing along with the | |
| 863 evaluation list.) | |
| 864 | |
| 865 | |
| 866 @node Coverage Testing | |
| 867 @subsection Coverage Testing | |
| 868 | |
| 869 @cindex coverage testing | |
| 870 @cindex frequency counts | |
| 871 @cindex performance analysis | |
| 872 Edebug provides a rudimentary coverage tester and display of execution | |
| 873 frequency. Frequency counts are always accumulated, both before and | |
| 874 after evaluation of each instrumented expression, even if the execution | |
| 875 mode is @code{Go-nonstop}. Coverage testing is only done if the option | |
| 876 @code{edebug-test-coverage} is non-@code{nil} because this is relatively | |
| 877 expensive. Both data sets are displayed by @kbd{M-x | |
| 878 edebug-display-freq-count}. | |
| 879 | |
| 880 @deffn Command edebug-display-freq-count | |
| 881 Display the frequency count data for each line of the current | |
| 882 definition. The frequency counts are inserted as comment lines after | |
| 883 each line, and you can undo all insertions with one @code{undo} command. | |
| 884 The counts are inserted starting under the @kbd{(} before an expression | |
| 885 or the @kbd{)} after an expression, or on the last char of a symbol. | |
| 886 The counts are only displayed when they differ from previous counts on | |
| 887 the same line. | |
| 888 | |
| 889 If coverage is being tested, whenever all known results of an expression | |
| 890 are @code{eq}, the char @kbd{=} will be appended after the count | |
| 891 for that expression. Note that this is always the case for an | |
| 892 expression only evaluated once. | |
| 893 | |
| 894 To clear the frequency count and coverage data for a definition, | |
| 895 reinstrument it. | |
| 896 | |
| 897 @end deffn | |
| 898 | |
| 899 For example, after evaluating @code{(fac 5)} with an embedded | |
| 900 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when | |
| 901 the breakpoint is reached, the frequency data is looks like this: | |
| 902 | |
| 903 @example | |
| 904 (defun fac (n) | |
| 905 (if (= n 0) (edebug)) | |
| 444 | 906 ;#6 1 0 =5 |
| 428 | 907 (if (< 0 n) |
| 444 | 908 ;#5 = |
| 428 | 909 (* n (fac (1- n))) |
| 444 | 910 ;# 5 0 |
| 428 | 911 1)) |
| 444 | 912 ;# 0 |
| 428 | 913 @end example |
| 914 | |
| 915 The comment lines show that @code{fac} has been called 6 times. The | |
| 916 first @code{if} statement has returned 5 times with the same result each | |
| 917 time, and the same is true for the condition on the second @code{if}. | |
| 918 The recursive call of @code{fac} has not returned at all. | |
| 919 | |
| 920 | |
| 921 @node The Outside Context | |
| 922 @subsection The Outside Context | |
| 923 | |
| 924 Edebug tries to be transparent to the program you are debugging. In | |
| 925 addition, most evaluations you do within Edebug (see @ref{Edebug Eval}) | |
| 926 occur in the same outside context which is temporarily restored for the | |
| 927 evaluation. But Edebug is not completely successful and this section | |
| 928 explains precisely how it fails. Edebug operation unavoidably alters | |
| 929 some data in XEmacs, and this can interfere with debugging certain | |
| 930 programs. Also notice that Edebug's protection against change of | |
| 931 outside data means that any side effects @emph{intended} by the user in | |
| 932 the course of debugging will be defeated. | |
| 933 | |
| 934 @menu | |
| 935 * Checking Whether to Stop:: When Edebug decides what to do. | |
| 936 * Edebug Display Update:: When Edebug updates the display. | |
| 937 * Edebug Recursive Edit:: When Edebug stops execution. | |
| 938 @end menu | |
| 939 | |
| 940 | |
| 941 @node Checking Whether to Stop | |
| 942 @subsubsection Checking Whether to Stop | |
| 943 | |
| 944 Whenever Edebug is entered just to think about whether to take some | |
| 945 action, it needs to save and restore certain data. | |
| 946 | |
| 947 @itemize @bullet | |
| 444 | 948 @item |
| 428 | 949 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both |
| 950 incremented one time to reduce Edebug's impact on the stack. | |
| 951 You could, however, still run out of stack space when using Edebug. | |
| 952 | |
| 444 | 953 @item |
| 428 | 954 The state of keyboard macro execution is saved and restored. While |
| 955 Edebug is active, @code{executing-macro} is bound to | |
| 956 @code{edebug-continue-kbd-macro}. | |
| 957 | |
| 958 @end itemize | |
| 959 | |
| 960 | |
| 961 @node Edebug Display Update | |
| 962 @subsubsection Edebug Display Update | |
| 963 | |
| 964 When Edebug needs to display something (e.g., in trace mode), it saves | |
| 965 the current window configuration from ``outside'' Edebug. When you exit | |
| 966 Edebug (by continuing the program), it restores the previous window | |
| 967 configuration. | |
| 968 | |
| 969 XEmacs redisplays only when it pauses. Usually, when you continue | |
| 970 execution, the program comes back into Edebug at a breakpoint or after | |
| 971 stepping without pausing or reading input in between. In such cases, | |
| 972 XEmacs never gets a chance to redisplay the ``outside'' configuration. | |
| 973 What you see is the same window configuration as the last time Edebug | |
| 974 was active, with no interruption. | |
| 975 | |
| 976 Entry to Edebug for displaying something also saves and restores the | |
| 977 following data, but some of these are deliberately not restored if an | |
| 978 error or quit signal occurs. | |
| 979 | |
| 980 @itemize @bullet | |
| 444 | 981 @item |
| 428 | 982 @cindex current buffer point and mark (Edebug) |
| 983 Which buffer is current, and where point and mark are in the current | |
| 984 buffer are saved and restored. | |
| 985 | |
| 444 | 986 @item |
| 428 | 987 @cindex window configuration (Edebug) |
| 988 @findex save-excursion (Edebug) | |
| 989 @vindex edebug-save-windows | |
| 990 The Edebug Display Update, is saved and restored if | |
| 991 @code{edebug-save-windows} is non-@code{nil}. It is not restored on | |
| 992 error or quit, but the outside selected window @emph{is} reselected even | |
| 444 | 993 on error or quit in case a @code{save-excursion} is active. |
| 428 | 994 If the value of @code{edebug-save-windows} is a list, only the listed |
| 995 windows are saved and restored. | |
| 996 | |
| 997 The window start and horizontal scrolling of the source code buffer are | |
| 998 not restored, however, so that the display remains coherent. | |
| 999 | |
| 1000 @item | |
| 1001 @vindex edebug-save-displayed-buffer-points | |
| 1002 The value of point in each displayed buffer is saved and restored if | |
| 1003 @code{edebug-save-displayed-buffer-points} is non-@code{nil}. | |
| 1004 | |
| 1005 @item | |
| 1006 The variables @code{overlay-arrow-position} and | |
| 1007 @code{overlay-arrow-string} are saved and restored. So you can safely | |
| 1008 invoke Edebug from the recursive edit elsewhere in the same buffer. | |
| 1009 | |
| 444 | 1010 @item |
| 428 | 1011 @code{cursor-in-echo-area} is locally bound to @code{nil} so that |
| 1012 the cursor shows up in the window. | |
| 1013 | |
| 1014 @end itemize | |
| 1015 | |
| 1016 | |
| 1017 @node Edebug Recursive Edit | |
| 1018 @subsubsection Edebug Recursive Edit | |
| 1019 | |
| 1020 When Edebug is entered and actually reads commands from the user, it | |
| 1021 saves (and later restores) these additional data: | |
| 1022 | |
| 1023 @itemize @bullet | |
| 1024 @item | |
| 1025 The current match data, for whichever buffer was current. | |
| 1026 | |
| 1027 @item | |
| 1028 @code{last-command}, @code{this-command}, @code{last-command-char}, | |
| 1029 @code{last-input-char}, @code{last-input-event}, | |
| 1030 @code{last-command-event}, | |
| 1031 @code{last-event-frame}, @code{last-nonmenu-event}, and | |
| 1032 @code{track-mouse} . Commands used within Edebug do not affect these | |
| 1033 variables outside of Edebug. | |
| 1034 | |
| 1035 The key sequence returned by @code{this-command-keys} is changed by | |
| 1036 executing commands within Edebug and there is no way to reset | |
| 1037 the key sequence from Lisp. | |
| 1038 | |
| 1039 For Emacs 18, Edebug cannot save and restore the value of | |
| 1040 @code{unread-command-char}. Entering Edebug while this variable has | |
| 1041 a nontrivial value can interfere with execution of the program you are | |
| 1042 debugging. | |
| 1043 | |
| 1044 @item | |
| 1045 Complex commands executed while in Edebug are added to the variable | |
| 1046 @code{command-history}. In rare cases this can alter execution. | |
| 1047 | |
| 1048 @item | |
| 1049 Within Edebug, the recursion depth appears one deeper than the recursion | |
| 1050 depth outside Edebug. This is not true of the automatically updated | |
| 1051 evaluation list window. | |
| 1052 | |
| 1053 @item | |
| 1054 @code{standard-output} and @code{standard-input} are bound to @code{nil} | |
| 1055 by the @code{recursive-edit}, but Edebug temporarily restores them during | |
| 1056 evaluations. | |
| 1057 | |
| 444 | 1058 @item |
| 428 | 1059 The state of keyboard macro definition is saved and restored. While |
| 1060 Edebug is active, @code{defining-kbd-macro} is bound to | |
| 1061 @code{edebug-continue-kbd-macro}. | |
| 1062 | |
| 1063 @end itemize | |
| 1064 | |
| 1065 | |
| 1066 @node Instrumenting Macro Calls | |
| 1067 @subsection Instrumenting Macro Calls | |
| 1068 | |
| 1069 When Edebug instruments an expression that calls a Lisp macro, it needs | |
| 1070 additional advice to do the job properly. This is because there is no | |
| 1071 way to tell which subexpressions of the macro call may be evaluated. | |
| 1072 (Evaluation may occur explicitly in the macro body, or when the | |
| 1073 resulting expansion is evaluated, or any time later.) You must explain | |
| 1074 the format of macro call arguments by using @code{def-edebug-spec} to | |
| 1075 define an @dfn{Edebug specification} for each macro. | |
| 1076 | |
| 444 | 1077 @defmac def-edebug-spec macro specification |
| 428 | 1078 Specify which expressions of a call to macro @var{macro} are forms to be |
| 1079 evaluated. For simple macros, the @var{specification} often looks very | |
| 1080 similar to the formal argument list of the macro definition, but | |
| 1081 specifications are much more general than macro arguments. | |
| 1082 | |
| 1083 The @var{macro} argument may actually be any symbol, not just a macro | |
| 1084 name. | |
| 1085 | |
| 1086 Unless you are using Emacs 19 or XEmacs, this macro is only defined | |
| 1087 in Edebug, so you may want to use the following which is equivalent: | |
| 1088 @code{(put '@var{macro} 'edebug-form-spec '@var{specification})} | |
| 444 | 1089 @end defmac |
| 428 | 1090 |
| 1091 Here is a simple example that defines the specification for the | |
| 1092 @code{for} macro described in the XEmacs Lisp Reference Manual, followed | |
| 1093 by an alternative, equivalent specification. | |
| 1094 | |
| 1095 @example | |
| 1096 (def-edebug-spec for | |
| 1097 (symbolp "from" form "to" form "do" &rest form)) | |
| 1098 | |
| 1099 (def-edebug-spec for | |
| 1100 (symbolp ['from form] ['to form] ['do body])) | |
| 1101 @end example | |
| 1102 | |
| 1103 Here is a table of the possibilities for @var{specification} and how each | |
| 1104 directs processing of arguments. | |
| 1105 | |
| 1106 @table @bullet | |
| 1107 | |
| 1108 @item @code{t} | |
| 1109 All arguments are instrumented for evaluation. | |
| 1110 | |
| 1111 @item @code{0} | |
| 1112 None of the arguments is instrumented. | |
| 1113 | |
| 1114 @item a symbol | |
| 1115 The symbol must have an Edebug specification which is used instead. | |
| 1116 This indirection is repeated until another kind of specification is | |
| 1117 found. This allows you to inherit the specification for another macro. | |
| 1118 | |
| 1119 @item a list | |
| 1120 The elements of the list describe the types of the arguments of a | |
| 1121 calling form. The possible elements of a specification list are | |
| 1122 described in the following sections. | |
| 1123 @end table | |
| 1124 | |
| 1125 @menu | |
| 1126 * Specification List:: How to specify complex patterns of evaluation. | |
| 1127 * Backtracking:: What Edebug does when matching fails. | |
| 1128 * Debugging Backquote:: Debugging Backquote | |
| 1129 * Specification Examples:: To help understand specifications. | |
| 1130 @end menu | |
| 1131 | |
| 1132 | |
| 1133 @node Specification List | |
| 1134 @subsubsection Specification List | |
| 1135 | |
| 1136 @cindex Edebug specification list | |
| 1137 A @dfn{specification list} is required for an Edebug specification if | |
| 1138 some arguments of a macro call are evaluated while others are not. Some | |
| 1139 elements in a specification list match one or more arguments, but others | |
| 1140 modify the processing of all following elements. The latter, called | |
| 1141 @dfn{keyword specifications}, are symbols beginning with @samp{@code{&}} | |
| 1142 (e.g. @code{&optional}). | |
| 1143 | |
| 1144 A specification list may contain sublists which match arguments that are | |
| 1145 themselves lists, or it may contain vectors used for grouping. Sublists | |
| 1146 and groups thus subdivide the specification list into a hierarchy of | |
| 1147 levels. Keyword specifications only apply to the remainder of the | |
| 1148 sublist or group they are contained in and there is an implicit grouping | |
| 1149 around a keyword specification and all following elements in the | |
| 1150 sublist or group. | |
| 1151 | |
| 1152 If a specification list fails | |
| 1153 at some level, then backtracking may be invoked to find some alternative | |
| 1154 at a higher level, or if no alternatives remain, an error will be | |
| 1155 signaled. See @ref{Backtracking} for more details. | |
| 1156 | |
| 1157 Edebug specifications provide at least the power of regular expression | |
| 1158 matching. Some context-free constructs are also supported: the matching | |
| 1159 of sublists with balanced parentheses, recursive processing of forms, | |
| 1160 and recursion via indirect specifications. | |
| 1161 | |
| 1162 Each element of a specification list may be one of the following, with | |
| 1163 the corresponding type of argument: | |
| 1164 | |
| 1165 @table @code | |
| 1166 | |
| 1167 @item sexp | |
| 1168 A single unevaluated expression. | |
| 1169 | |
| 1170 @item form | |
| 1171 A single evaluated expression, which is instrumented. | |
| 1172 | |
| 1173 @item place | |
| 1174 @findex edebug-unwrap | |
| 1175 A place as in the Common Lisp @code{setf} place argument. It will be | |
| 1176 instrumented just like a form, but the macro is expected to strip the | |
| 1177 instrumentation. Two functions, @code{edebug-unwrap} and | |
| 1178 @code{edebug-unwrap*}, are provided to strip the instrumentation one | |
| 1179 level or recursively at all levels. | |
| 1180 | |
| 1181 @item body | |
| 1182 Short for @code{&rest form}. See @code{&rest} below. | |
| 1183 | |
| 1184 @item function-form | |
| 1185 A function form: either a quoted function symbol, a quoted lambda expression, | |
| 1186 or a form (that should evaluate to a function symbol or lambda | |
| 1187 expression). This is useful when function arguments might be quoted | |
| 1188 with @code{quote} rather than @code{function} since the body of a lambda | |
| 1189 expression will be instrumented either way. | |
| 1190 | |
| 1191 @item lambda-expr | |
| 1192 An unquoted anonymous lambda expression. | |
| 1193 | |
| 1194 @item &optional | |
| 1195 @cindex &optional (Edebug) | |
| 1196 All following elements in the specification list are optional; as soon | |
| 444 | 1197 as one does not match, Edebug stops matching at this level. |
| 428 | 1198 |
| 1199 To make just a few elements optional followed by non-optional elements, | |
| 1200 use @code{[&optional @var{specs}@dots{}]}. To specify that several | |
| 1201 elements should all succeed together, use @code{&optional | |
| 1202 [@var{specs}@dots{}]}. See the @code{defun} example below. | |
| 1203 | |
| 1204 @item &rest | |
| 1205 @cindex &rest (Edebug) | |
| 1206 All following elements in the specification list are repeated zero or | |
| 1207 more times. All the elements need not match in the last repetition, | |
| 1208 however. | |
| 1209 | |
| 1210 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. | |
| 1211 To specify all elements must match on every repetition, use @code{&rest | |
| 1212 [@var{specs}@dots{}]}. | |
| 1213 | |
| 1214 @item &or | |
| 1215 @cindex &or (Edebug) | |
| 1216 Each of the following elements in the specification list is an | |
| 1217 alternative, processed left to right until one matches. One of the | |
| 1218 alternatives must match otherwise the @code{&or} specification fails. | |
| 1219 | |
| 1220 Each list element following @code{&or} is a single alternative even if | |
| 1221 it is a keyword specification. (This breaks the implicit grouping rule.) | |
| 1222 To group two or more list elements as a single alternative, enclose them | |
| 1223 in @code{[@dots{}]}. | |
| 1224 | |
| 1225 @item ¬ | |
| 1226 @cindex ¬ (Edebug) | |
| 1227 Each of the following elements is matched as alternatives as if by using | |
| 1228 @code{&or}, but if any of them match, the specification fails. If none | |
| 1229 of them match, nothing is matched, but the @code{¬} specification | |
| 1230 succeeds. | |
| 1231 | |
| 444 | 1232 @item &define |
| 428 | 1233 @cindex &define (Edebug) |
| 1234 Indicates that the specification is for a defining form. The defining | |
| 1235 form itself is not instrumented (i.e. Edebug does not stop before and | |
| 1236 after the defining form), but forms inside it typically will be | |
| 1237 instrumented. The @code{&define} keyword should be the first element in | |
| 1238 a list specification. | |
| 1239 | |
| 1240 Additional specifications that may only appear after @code{&define} are | |
| 1241 described here. See the @code{defun} example below. | |
| 1242 | |
| 1243 @table @code | |
| 1244 | |
| 1245 @item name | |
| 444 | 1246 The argument, a symbol, is the name of the defining form. |
| 428 | 1247 But a defining form need not be named at all, in which |
| 1248 case a unique name will be created for it. | |
| 1249 | |
| 1250 The @code{name} specification may be used more than once in the | |
| 1251 specification and each subsequent use will append the corresponding | |
| 1252 symbol argument to the previous name with @samp{@code{@@}} between them. | |
| 1253 This is useful for generating unique but meaningful names for | |
| 1254 definitions such as @code{defadvice} and @code{defmethod}. | |
| 1255 | |
| 1256 @item :name | |
| 1257 The element following @code{:name} should be a symbol; it is used as an | |
| 1258 additional name component for the definition. This is useful to add a | |
| 1259 unique, static component to the name of the definition. It may be used | |
| 1260 more than once. No argument is matched. | |
| 1261 | |
| 1262 @item arg | |
| 1263 The argument, a symbol, is the name of an argument of the defining form. | |
| 1264 However, lambda list keywords (symbols starting with @samp{@code{&}}) | |
| 1265 are not allowed. See @code{lambda-list} and the example below. | |
| 1266 | |
| 1267 @item lambda-list | |
| 1268 @cindex lambda-list (Edebug) | |
| 1269 This matches the whole argument list of an XEmacs Lisp lambda | |
| 1270 expression, which is a list of symbols and the keywords | |
| 1271 @code{&optional} and @code{&rest} | |
| 1272 | |
| 1273 @item def-body | |
| 1274 The argument is the body of code in a definition. This is like | |
| 1275 @code{body}, described above, but a definition body must be instrumented | |
| 1276 with a different Edebug call that looks up information associated with | |
| 1277 the definition. Use @code{def-body} for the highest level list of forms | |
| 1278 within the definition. | |
| 1279 | |
| 1280 @item def-form | |
| 1281 The argument is a single, highest-level form in a definition. This is | |
| 1282 like @code{def-body}, except use this to match a single form rather than | |
| 1283 a list of forms. As a special case, @code{def-form} also means that | |
| 1284 tracing information is not output when the form is executed. See the | |
| 1285 @code{interactive} example below. | |
| 1286 | |
| 1287 @end table | |
| 1288 | |
| 1289 @item nil | |
| 1290 This is successful when there are no more arguments to match at the | |
| 1291 current argument list level; otherwise it fails. See sublist | |
| 1292 specifications and the backquote example below. | |
| 1293 | |
| 1294 @item gate | |
| 1295 @cindex preventing backtracking | |
| 1296 No argument is matched but backtracking through the gate is disabled | |
| 1297 while matching the remainder of the specifications at this level. This | |
| 1298 is primarily used to generate more specific syntax error messages. See | |
| 1299 @ref{Backtracking} for more details. Also see the @code{let} example | |
| 1300 below. | |
| 1301 | |
| 1302 @item @var{other-symbol} | |
| 1303 @cindex indirect specifications | |
| 1304 Any other symbol in a specification list may be a predicate or an | |
| 1305 indirect specification. | |
| 1306 | |
| 1307 If the symbol has an Edebug specification, this @dfn{indirect | |
| 1308 specification} should be either a list specification that is used in | |
| 1309 place of the symbol, or a function that is called to process the | |
| 1310 arguments. The specification may be defined with @code{def-edebug-spec} | |
| 1311 just as for macros. See the @code{defun} example below. | |
| 1312 | |
| 1313 Otherwise, the symbol should be a predicate. The predicate is called | |
| 1314 with the argument and the specification fails if the predicate fails. | |
| 1315 The argument is not instrumented. | |
| 1316 | |
| 1317 @findex keywordp | |
| 1318 @findex lambda-list-keywordp | |
| 1319 Predicates that may be used include: @code{symbolp}, @code{integerp}, | |
| 1320 @code{stringp}, @code{vectorp}, @code{atom} (which matches a number, | |
| 1321 string, symbol, or vector), @code{keywordp}, and | |
| 1322 @code{lambda-list-keywordp}. The last two, defined in @file{edebug.el}, | |
| 1323 test whether the argument is a symbol starting with @samp{@code{:}} and | |
| 1324 @samp{@code{&}} respectively. | |
| 1325 | |
| 1326 @item [@var{elements}@dots{}] | |
| 1327 @cindex [@dots{}] (Edebug) | |
| 1328 Rather than matching a vector argument, a vector treats | |
| 1329 the @var{elements} as a single @dfn{group specification}. | |
| 1330 | |
| 1331 @item "@var{string}" | |
| 1332 The argument should be a symbol named @var{string}. This specification | |
| 1333 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name | |
| 1334 of @var{symbol} is the @var{string}, but the string form is preferred. | |
| 1335 | |
| 1336 @item '@var{symbol} @r{or} (quote @var{symbol}) | |
| 1337 The argument should be the symbol @var{symbol}. But use a string | |
| 1338 specification instead. | |
| 1339 | |
| 1340 @item (vector @var{elements}@dots{}) | |
| 1341 The argument should be a vector whose elements must match the | |
| 1342 @var{elements} in the specification. See the backquote example below. | |
| 1343 | |
| 1344 @item (@var{elements}@dots{}) | |
| 1345 Any other list is a @dfn{sublist specification} and the argument must be | |
| 1346 a list whose elements match the specification @var{elements}. | |
| 1347 | |
| 1348 @cindex dotted lists (Edebug) | |
| 1349 A sublist specification may be a dotted list and the corresponding list | |
| 1350 argument may then be a dotted list. Alternatively, the last cdr of a | |
| 1351 dotted list specification may be another sublist specification (via a | |
| 1352 grouping or an indirect specification, e.g. @code{(spec . [(more | |
| 1353 specs@dots{})])}) whose elements match the non-dotted list arguments. | |
| 1354 This is useful in recursive specifications such as in the backquote | |
| 1355 example below. Also see the description of a @code{nil} specification | |
| 1356 above for terminating such recursion. | |
| 1357 | |
| 1358 Note that a sublist specification of the form @code{(specs . nil)} | |
| 1359 means the same as @code{(specs)}, and @code{(specs . | |
| 1360 (sublist-elements@dots{}))} means the same as @code{(specs | |
| 1361 sublist-elements@dots{})}. | |
| 1362 | |
| 1363 @end table | |
| 1364 | |
| 1365 @c Need to document extensions with &symbol and :symbol | |
| 1366 | |
| 1367 @node Backtracking | |
| 1368 @subsubsection Backtracking | |
| 1369 | |
| 1370 @cindex backtracking | |
| 1371 @cindex syntax error (Edebug) | |
| 1372 If a specification fails to match at some point, this does not | |
| 1373 necessarily mean a syntax error will be signaled; instead, | |
| 1374 @dfn{backtracking} will take place until all alternatives have been | |
| 1375 exhausted. Eventually every element of the argument list must be | |
| 1376 matched by some element in the specification, and every required element | |
| 1377 in the specification must match some argument. | |
| 1378 | |
| 1379 Backtracking is disabled for the remainder of a sublist or group when | |
| 1380 certain conditions occur, described below. Backtracking is reenabled | |
| 1381 when a new alternative is established by @code{&optional}, @code{&rest}, | |
| 1382 or @code{&or}. It is also reenabled initially when processing a | |
| 1383 sublist or group specification or an indirect specification. | |
| 1384 | |
| 1385 You might want to disable backtracking to commit to some alternative so | |
| 1386 that Edebug can provide a more specific syntax error message. Normally, | |
| 1387 if no alternative matches, Edebug reports that none matched, but if one | |
| 1388 alternative is committed to, Edebug can report how it failed to match. | |
| 1389 | |
| 1390 First, backtracking is disabled while matching any of the form | |
| 1391 specifications (i.e. @code{form}, @code{body}, @code{def-form}, and | |
| 1392 @code{def-body}). These specifications will match any form so any error | |
| 1393 must be in the form itself rather than at a higher level. | |
| 1394 | |
| 1395 Second, backtracking is disabled after successfully matching a quoted | |
| 1396 symbol or string specification, since this usually indicates a | |
| 1397 recognized construct. If you have a set of alternative constructs that | |
| 1398 all begin with the same symbol, you can usually work around this | |
| 1399 constraint by factoring the symbol out of the alternatives, e.g., | |
| 1400 @code{["foo" &or [first case] [second case] ...]}. | |
| 1401 | |
| 1402 Third, backtracking may be explicitly disabled by using the | |
| 1403 @code{gate} specification. This is useful when you know that | |
| 1404 no higher alternatives may apply. | |
| 1405 | |
| 1406 | |
| 1407 @node Debugging Backquote | |
| 1408 @subsubsection Debugging Backquote | |
| 1409 | |
| 1410 @findex ` (Edebug) | |
| 1411 @cindex backquote (Edebug) | |
| 1412 Backquote (@kbd{`}) is a macro that results in an expression that may or | |
| 1413 may not be evaluated. It is often used to simplify the definition of a | |
| 1414 macro to return an expression that is evaluated, but Edebug does not know | |
| 1415 when this is the case. However, the forms inside unquotes (@code{,} and | |
| 1416 @code{,@@}) are evaluated and Edebug instruments them. | |
| 1417 | |
| 1418 Nested backquotes are supported by Edebug, but there is a limit on the | |
| 1419 support of quotes inside of backquotes. Quoted forms (with @code{'}) | |
| 1420 are not normally evaluated, but if the quoted form appears immediately | |
| 1421 within @code{,} and @code{,@@} forms, Edebug treats this as a backquoted | |
| 1422 form at the next higher level (even if there is not a next higher level | |
| 1423 - this is difficult to fix). | |
| 1424 | |
| 1425 @findex edebug-` | |
| 1426 If the backquoted forms happen to be code intended to be evaluated, you | |
| 1427 can have Edebug instrument them by using @code{edebug-`} instead of the | |
| 1428 regular @code{`}. Unquoted forms can always appear inside | |
| 1429 @code{edebug-`} anywhere a form is normally allowed. But @code{(, | |
| 1430 @var{form})} may be used in two other places specially recognized by | |
| 1431 Edebug: wherever a predicate specification would match, and at the head | |
| 1432 of a list form in place of a function name or lambda expression. The | |
| 1433 @var{form} inside a spliced unquote, @code{(,@@ @var{form})}, will be | |
| 1434 wrapped, but the unquote form itself will not be wrapped since this | |
| 1435 would interfere with the splicing. | |
| 1436 | |
| 1437 There is one other complication with using @code{edebug-`}. If the | |
| 1438 @code{edebug-`} call is in a macro and the macro may be called from code | |
| 1439 that is also instrumented, and if unquoted forms contain any macro | |
| 1440 arguments bound to instrumented forms, then you should modify the | |
| 1441 specification for the macro as follows: the specifications for those | |
| 1442 arguments must use @code{def-form} instead of @code{form}. (This is to | |
| 1443 reestablish the Edebugging context for those external forms.) | |
| 1444 | |
| 444 | 1445 For example, the @code{for} macro |
| 428 | 1446 @c (@pxref{Problems with Macros}) @c in XEmacs Lisp Reference Manual |
| 1447 (@pxref{Problems with Macros,,,, XEmacs Lisp Reference Manual}) @c Edebug Doc | |
| 1448 is shown here but with @code{edebug-`} | |
| 1449 substituted for regular @code{`}. | |
| 1450 | |
| 1451 @example | |
| 1452 (defmacro inc (var) | |
| 1453 (list 'setq var (list '1+ var))) | |
| 1454 | |
| 1455 (defmacro for (var from init to final do &rest body) | |
| 1456 (let ((tempvar (make-symbol "max"))) | |
| 1457 (edebug-` (let (((, var) (, init)) | |
| 1458 ((, tempvar) (, final))) | |
| 1459 (while (<= (, var) (, tempvar)) | |
| 1460 (,@ body) | |
| 1461 (inc (, var))))))) | |
| 1462 @end example | |
| 1463 | |
| 1464 Here is the corresponding modified Edebug specification and some code | |
| 1465 that calls the macro: | |
| 1466 | |
| 1467 @example | |
| 1468 (def-edebug-spec for | |
| 1469 (symbolp "from" def-form "to" def-form "do" &rest def-form)) | |
| 1470 | |
| 1471 (let ((n 5)) | |
| 1472 (for i from n to (* n (+ n 1)) do | |
| 1473 (message "%s" i))) | |
| 1474 @end example | |
| 1475 | |
| 1476 After instrumenting the @code{for} macro and the macro call, Edebug | |
| 1477 first steps to the beginning of the macro call, then into the macro | |
| 1478 body, then through each of the unquoted expressions in the backquote | |
| 1479 showing the expressions that will be embedded in the backquote form. | |
| 1480 Then when the macro expansion is evaluated, Edebug will step through the | |
| 1481 @code{let} form and each time it gets to an unquoted form, it will jump | |
| 1482 back to an argument of the macro call to step through that expression. | |
| 1483 Finally stepping will continue after the macro call. Even more | |
| 1484 convoluted execution paths may result when using anonymous functions. | |
| 1485 | |
| 1486 @vindex edebug-unwrap-results | |
| 1487 When the result of an expression is an instrumented expression, it is | |
| 1488 difficult to see the expression inside the instrumentation. So | |
| 1489 you may want to set the option @code{edebug-unwrap-results} to a | |
| 1490 non-@code{nil} value while debugging such expressions, but it would slow | |
| 1491 Edebug down to always do this. | |
| 1492 | |
| 1493 | |
| 1494 @node Specification Examples | |
| 1495 @subsubsection Specification Examples | |
| 1496 | |
| 1497 Here we provide several examples of Edebug specifications to show | |
| 1498 many of its capabilities. | |
| 1499 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
1500 A @code{let} special operator has a sequence of bindings and a body. Each |
| 428 | 1501 of the bindings is either a symbol or a sublist with a symbol and |
| 1502 optional value. In the specification below, notice the @code{gate} | |
| 1503 inside of the sublist to prevent backtracking. | |
| 1504 | |
| 1505 @example | |
| 1506 (def-edebug-spec let | |
| 1507 ((&rest | |
| 1508 &or symbolp (gate symbolp &optional form)) | |
| 1509 body)) | |
| 1510 @end example | |
| 1511 | |
| 1512 Edebug uses the following specifications for @code{defun} and | |
| 1513 @code{defmacro} and the associated argument list and @code{interactive} | |
| 1514 specifications. It is necessary to handle the expression argument of an | |
| 1515 interactive form specially since it is actually evaluated outside of the | |
| 1516 function body. | |
| 1517 | |
| 1518 @example | |
| 1519 (def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec} | |
| 444 | 1520 (def-edebug-spec defun |
| 1521 (&define name lambda-list | |
| 428 | 1522 [&optional stringp] ; @r{Match the doc string, if present.} |
| 1523 [&optional ("interactive" interactive)] | |
| 1524 def-body)) | |
| 1525 | |
| 1526 (def-edebug-spec lambda-list | |
| 1527 (([&rest arg] | |
| 1528 [&optional ["&optional" arg &rest arg]] | |
| 1529 &optional ["&rest" arg] | |
| 1530 ))) | |
| 1531 | |
| 1532 (def-edebug-spec interactive | |
| 1533 (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} | |
| 1534 @end example | |
| 1535 | |
| 1536 The specification for backquote below illustrates how to match | |
| 1537 dotted lists and use @code{nil} to terminate recursion. It also | |
| 1538 illustrates how components of a vector may be matched. (The actual | |
| 1539 specification provided by Edebug does not support dotted lists because | |
| 1540 doing so causes very deep recursion that could fail.) | |
| 1541 | |
| 1542 @example | |
| 1543 (def-edebug-spec ` (backquote-form)) ;; alias just for clarity | |
| 1544 | |
| 1545 (def-edebug-spec backquote-form | |
| 1546 (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) | |
| 1547 (backquote-form . [&or nil backquote-form]) | |
| 1548 (vector &rest backquote-form) | |
| 1549 sexp)) | |
| 1550 @end example | |
| 1551 | |
| 1552 | |
| 1553 @node Edebug Options | |
| 1554 @subsection Edebug Options | |
| 1555 | |
| 1556 These options affect the behavior of Edebug: | |
| 1557 | |
| 1558 @defopt edebug-setup-hook | |
| 1559 Functions to call before Edebug is used. Each time it is set to a new | |
| 1560 value, Edebug will call those functions once and then | |
| 1561 @code{edebug-setup-hook} is reset to @code{nil}. You could use this to | |
| 1562 load up Edebug specifications associated with a package you are using | |
| 1563 but only when you also use Edebug. | |
| 1564 See @ref{Instrumenting}. | |
| 1565 @end defopt | |
| 1566 | |
| 1567 @defopt edebug-all-defs | |
| 1568 If non-@code{nil}, normal evaluation of any defining forms (e.g. | |
| 1569 @code{defun} and @code{defmacro}) will instrument them for Edebug. This | |
| 1570 applies to @code{eval-defun}, @code{eval-region}, and | |
| 1571 @code{eval-current-buffer}. | |
| 1572 | |
| 1573 Use the command @kbd{M-x edebug-all-defs} to toggle the value of | |
| 1574 this variable. You may want to make this variable local to each | |
| 1575 buffer by calling @code{(make-local-variable 'edebug-all-defs)} in your | |
| 1576 @code{emacs-lisp-mode-hook}. | |
| 1577 See @ref{Instrumenting}. | |
| 1578 @end defopt | |
| 1579 | |
| 1580 @defopt edebug-all-forms | |
| 1581 If non-@code{nil}, normal evaluation of any forms by @code{eval-defun}, | |
| 1582 @code{eval-region}, and @code{eval-current-buffer} will instrument them | |
| 1583 for Edebug. | |
| 1584 | |
| 1585 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this | |
| 1586 option. | |
| 1587 See @ref{Instrumenting}. | |
| 1588 @end defopt | |
| 1589 | |
| 1590 @defopt edebug-save-windows | |
| 1591 If non-@code{nil}, save and restore window configuration on Edebug | |
| 1592 calls. It takes some time to do this, so if your program does not care | |
| 1593 what happens to data about windows, you may want to set this variable to | |
| 1594 @code{nil}. | |
| 1595 | |
| 1596 If the value is a list, only the listed windows are saved and | |
| 444 | 1597 restored. |
| 428 | 1598 |
| 1599 @kbd{M-x edebug-toggle-save-windows} may be used to change this variable. | |
| 1600 This command is bound to @kbd{W} in source code buffers. | |
| 1601 See @ref{Edebug Display Update}. | |
| 1602 @end defopt | |
| 1603 | |
| 1604 @defopt edebug-save-displayed-buffer-points | |
| 1605 If non-@code{nil}, save and restore point in all displayed buffers. | |
| 1606 This is necessary if you are debugging code that changes the point of a | |
| 1607 buffer which is displayed in a non-selected window. If Edebug or the | |
| 1608 user then selects the window, the buffer's point will be changed to the | |
| 1609 window's point. | |
| 1610 | |
| 1611 This is an expensive operation since it visits each window and therefore | |
| 1612 each displayed buffer twice for each Edebug activation, so it is best to | |
| 1613 avoid it if you can. | |
| 1614 See @ref{Edebug Display Update}. | |
| 1615 @end defopt | |
| 1616 | |
| 1617 | |
| 1618 @defopt edebug-initial-mode | |
| 1619 If this variable is non-@code{nil}, it specifies the initial execution | |
| 1620 mode for Edebug when it is first activated. Possible values are | |
| 1621 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace}, | |
| 1622 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}. | |
| 1623 | |
| 444 | 1624 The default value is @code{step}. |
| 428 | 1625 See @ref{Edebug Execution Modes}. |
| 1626 @end defopt | |
| 1627 | |
| 1628 @defopt edebug-trace | |
| 1629 @findex edebug-print-trace-before | |
| 1630 @findex edebug-print-trace-after | |
| 1631 Non-@code{nil} means display a trace of function entry and exit. | |
| 1632 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one | |
| 444 | 1633 function entry or exit per line, indented by the recursion level. |
| 428 | 1634 |
| 444 | 1635 The default value is @code{nil}. |
| 428 | 1636 |
| 1637 Also see @code{edebug-tracing}. | |
| 1638 See @ref{Tracing}. | |
| 1639 @end defopt | |
| 1640 | |
| 444 | 1641 @defopt edebug-test-coverage |
| 428 | 1642 If non-@code{nil}, Edebug tests coverage of all expressions debugged. |
| 1643 This is done by comparing the result of each expression | |
| 1644 with the previous result. Coverage is considered OK if two different | |
| 1645 results are found. So to sufficiently test the coverage of your code, | |
| 1646 try to execute it under conditions that evaluate all expressions more | |
| 1647 than once, and produce different results for each expression. | |
| 1648 | |
| 1649 Use @kbd{M-x edebug-display-freq-count} to display the frequency count | |
| 1650 and coverage information for a definition. | |
| 1651 See @ref{Coverage Testing}. | |
| 1652 @end defopt | |
| 1653 | |
| 444 | 1654 @defopt edebug-continue-kbd-macro |
| 428 | 1655 If non-@code{nil}, continue defining or executing any keyboard macro |
| 1656 that is executing outside of Edebug. Use this with caution since it is not | |
| 1657 debugged. | |
| 1658 See @ref{Edebug Execution Modes}. | |
| 1659 @end defopt | |
| 1660 | |
| 1661 @defopt edebug-print-length | |
| 1662 If non-@code{nil}, bind @code{print-length} to this while printing | |
| 1663 results in Edebug. The default value is @code{50}. | |
| 1664 See @ref{Printing in Edebug}. | |
| 1665 @end defopt | |
| 1666 | |
| 444 | 1667 @defopt edebug-print-level |
| 428 | 1668 If non-@code{nil}, bind @code{print-level} to this while printing |
| 1669 results in Edebug. The default value is @code{50}. | |
| 1670 @end defopt | |
| 1671 | |
| 444 | 1672 @defopt edebug-print-circle |
| 428 | 1673 If non-@code{nil}, bind @code{print-circle} to this while printing |
| 1674 results in Edebug. The default value is @code{nil}. | |
| 1675 @end defopt | |
| 1676 | |
| 1677 @defopt edebug-on-error | |
| 1678 @code{debug-on-error} is bound to this while Edebug is active. | |
| 1679 See @ref{Trapping Errors}. | |
| 1680 @end defopt | |
| 1681 | |
| 1682 @defopt edebug-on-quit | |
| 1683 @code{debug-on-quit} is bound to this while Edebug is active. | |
| 1684 See @ref{Trapping Errors}. | |
| 1685 @end defopt | |
| 1686 | |
| 1687 @defopt edebug-unwrap-results | |
| 1688 Non-@code{nil} if Edebug should unwrap results of expressions. | |
| 1689 This is useful when debugging macros where the results of expressions | |
| 1690 are instrumented expressions. But don't do this when results might be | |
| 1691 circular or an infinite loop will result. | |
| 1692 See @ref{Debugging Backquote}. | |
| 1693 @end defopt | |
| 1694 | |
| 1695 @defopt edebug-global-break-condition | |
| 1696 If non-@code{nil}, an expression to test for at every stop point. | |
| 444 | 1697 If the result is non-@code{nil}, then break. Errors are ignored. |
| 428 | 1698 See @ref{Global Break Condition}. |
| 1699 @end defopt |