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